Skip to content

feat: add provider profile registry and policy layer composition foundation #947

Closed
#1037
Closed
feat: add provider profile registry and policy layer composition foundation#947
#1037
Labels
area:cliCLI-related workarea:gatewayGateway server and control-plane workarea:policyPolicy engine and policy lifecycle workstate:agent-readyApproved for agent implementationstate:in-progressWork is currently in progresstopic:compatibilityCompatibility-related worktopic:testing

Description

@johntmyers
johntmyers
opened on Apr 23, 2026

Problem Statement

Provider configuration and policy configuration are currently separate workflows. Provider records can carry credentials, but the network endpoints, binaries, L7 access presets, and deny rules that make those providers usable still need to be authored manually in sandbox policy. Roadmap issue #896 proposes declarative provider profiles to unify that metadata.

This first implementation slice should establish the profile and policy-composition foundation while preserving backwards compatibility for existing provider records and existing sandbox policies.

Proposed Design

Introduce provider type profiles as declarative provider metadata that can describe expected credentials, known endpoints, binaries, optional verification metadata, and future inference metadata. Ship default embedded profiles for the existing built-in provider types, and adapt the existing hardcoded provider registry/discovery behavior to read from those profiles where possible.

Add the initial protobuf/API surface needed to expose provider profiles and browse provider types from clients. The first CLI surface should support listing available provider types and inspecting enough profile metadata to understand what policy surface a provider contributes.

Add a policy layer composition model that preserves the existing sandbox enforcement contract: the sandbox still receives one effective SandboxPolicy, but the gateway/server-side policy lifecycle can compose separate base, provider, and user policy layers into that effective policy.

The first PR should explicitly distinguish legacy provider behavior from profile-backed policy injection. Existing provider records and existing sandboxes must not silently gain new provider-generated network policy unless they are created or upgraded through the new profile-aware path. A provider/profile marker such as profile_id, profile_policy_enabled, or equivalent attachment metadata should make this compatibility boundary explicit.

Composition should concatenate provider-generated rules and user-authored rules rather than merging duplicate endpoints into a single rule. Duplicate host/port entries across layers are expected and must be handled by the existing OPA semantics: allow decisions are the union of matching allows, deny rules are the union of matching denies, and deny wins globally.

Definition of Done

  • Default provider profiles exist for the current built-in provider types without removing support for existing provider records.
  • Existing provider discovery and credential env-var metadata continue to work for current providers.
  • Protobuf/API surface exists for browsing provider types/profiles.
  • CLI supports browsing provider types, grouped or summarized by profile category.
  • Policy composition can produce one effective SandboxPolicy from base, provider, and user layers.
  • Full policy replacement updates only the user-authored layer and does not remove provider-generated entries.
  • Incremental policy updates and policy-advisor approvals mutate only the user-authored layer.
  • Existing user policies with endpoints that overlap provider defaults remain valid and continue to compose deterministically.
  • Global policy behavior remains unchanged and still blocks per-sandbox policy mutation paths.
  • Tests cover duplicate endpoint composition, allow union, deny precedence, layer replacement semantics, and legacy compatibility behavior.
  • Architecture documentation is updated to describe provider profiles, compatibility behavior, and the initial layer-composition model.

Out of Scope

  • Runtime provider attach/detach for already-running sandboxes.
  • Migration from placeholder/env scanning credential injection to profile-defined proxy-side injection.
  • Credential verification probes during provider creation.
  • Multi-provider inference.local route generation.
  • Credential refresh lifecycle and OAuth2 rotation.
  • Custom user registration/export of provider profiles, unless needed as a minimal internal API for defaults.

Agent Investigation

Related roadmap: #896.

Relevant current implementation points:

  • crates/openshell-providers/src/lib.rs has a hardcoded ProviderRegistry and provider plugin trait for discovery/env var metadata.
  • proto/datamodel.proto stores provider records with type, credentials, and config only.
  • proto/sandbox.proto already carries network rules, endpoints, binaries, L7 access presets, and deny rules in SandboxPolicy.
  • crates/openshell-policy/src/merge.rs provides existing incremental policy merge behavior for user-authored policy changes.
  • crates/openshell-server/src/grpc/policy.rs currently treats sandbox policy updates as mutations of one policy revision and blocks sandbox-scoped updates when a global policy is active.
  • crates/openshell-server/src/grpc/provider.rs resolves provider credentials into environment entries for the current placeholder-based credential injection path.
  • crates/openshell-sandbox/src/secrets.rs implements the current placeholder resolver and should remain compatible until profile-defined proxy-side injection is implemented in a later issue.

Activity

  1. johntmyers
    added
    area:cliCLI-related work
    area:policyPolicy engine and policy lifecycle work
    area:gatewayGateway server and control-plane work
    topic:compatibilityCompatibility-related work
    topic:testing
    on Apr 23, 2026
  2. johntmyers
    added a parent issue on Apr 23, 2026

  3. johntmyers commented on Apr 27, 2026

    @johntmyers
    johntmyers
    on Apr 27, 2026
    CollaboratorAuthor

    🏗️ build-plan

    Implementation Plan

    Issue type: feat
    Complexity: High
    Confidence: Medium — the target behavior is clear, but this crosses provider registry, protobuf/API, server policy lifecycle, CLI, tests, and docs.

    Summary

    Build the first provider-profile foundation without changing credential injection semantics. The implementation will add profile metadata for existing provider types, expose profile browsing through API/CLI, and introduce a policy composition path that can produce a normal effective SandboxPolicy from base/static policy, opted-in provider profile policy, and user-authored network policy.

    Backwards compatibility is the primary constraint: existing provider records and existing sandbox attachments must remain legacy/manual unless explicitly created or upgraded through a profile-aware path. The first iteration should not migrate credential injection away from the current placeholder/env resolver.

    Scope

    • proto/datamodel.proto: extend provider data or add profile-related metadata needed to distinguish legacy providers from profile-backed policy injection.
    • proto/openshell.proto: add provider-profile browse RPC messages and service methods.
    • crates/openshell-providers/: add profile structs/registry/default profiles and adapt existing provider plugins to source credential env-var metadata from profiles where practical.
    • crates/openshell-server/src/grpc/provider.rs: serve provider profile browse APIs and preserve legacy provider CRUD behavior.
    • crates/openshell-server/src/grpc/policy.rs: introduce effective-policy composition in the sandbox settings path while keeping global policy behavior unchanged.
    • crates/openshell-policy/: add reusable composition helpers and tests for layer semantics.
    • crates/openshell-cli/src/main.rs and crates/openshell-cli/src/run.rs: add the initial openshell provider types CLI surface.
    • architecture/sandbox-providers.md and/or architecture/security-policy.md: document profile metadata, compatibility behavior, and layer composition.

    Implementation Steps

    1. Add typed provider profile structures and embedded default profiles for current built-in provider types.
    2. Add compatibility metadata so profile-backed policy contribution is explicit rather than inferred from provider.type alone.
    3. Add provider profile browse protobufs/RPCs and server handlers.
    4. Add CLI support for browsing available provider types.
    5. Add policy composition helpers that concatenate base, enabled provider, and user network policy layers into one effective SandboxPolicy.
    6. Wire composition into the sandbox policy fetch/settings path without changing sandbox-side enforcement or credential injection.
    7. Add focused unit/integration tests around profile registry behavior, CLI/API browsing, legacy compatibility, and layer composition semantics.
    8. Update architecture docs for the first-iteration behavior and deferred credential-injection migration.

    Test Plan

    • Unit tests: provider profile registry/default profile loading; policy composition helper behavior; legacy provider compatibility markers; duplicate network rule names/endpoints.
    • Server tests: profile browse handlers; effective policy composition for legacy versus profile-enabled providers; global policy override still bypasses/blocks sandbox-scoped mutation paths as today.
    • CLI tests: provider types output/grouping/sorting where existing CLI integration patterns support it.
    • OPA/policy tests: existing overlapping-policy allow/deny behavior should remain green; add composition-level tests for allow union and deny precedence where not already covered.
    • E2E tests: not required for this first slice unless sandbox startup policy fetch behavior changes in a way not covered by server/unit tests.

    Risks & Open Questions

    • The cleanest compatibility boundary may be provider-level metadata or attachment-level metadata. Attachment-level state is semantically better for mixed legacy/profile usage, but may require a larger protobuf/storage migration than this first PR should take on.
    • Policy composition should remain JIT. If an effective policy hash or cached payload is needed for reload detection, it must be treated as derived data; layer inputs remain the source of truth
    • Existing code assumes sandbox policy updates mutate one policy document. The implementation must avoid letting policy set accidentally replace provider-generated entries or static base fields.
    • Default provider endpoint/binary profiles should be conservative in the first iteration to avoid over-broad policy grants.

    Documentation Impact

    Update provider and policy architecture docs to explain:

    • provider profiles versus legacy provider records,
    • why profile policy contribution is opt-in for existing providers/sandboxes,
    • the base/provider/user layer model,
    • credential injection remaining on the current placeholder/env path for this first iteration,
    • deferred follow-up work for proxy-side profile credential injection, attach/detach, inference routing, verification, and refresh.

    Revision 1 — initial plan

  4. johntmyers
    added
    state:review-readyReady for human review
    state:agent-readyApproved for agent implementation
    state:in-progressWork is currently in progress
    and removed
    state:review-readyReady for human review
    on Apr 27, 2026
  5. johntmyers
    closed this as completedin #1037on May 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:cliCLI-related workarea:gatewayGateway server and control-plane workarea:policyPolicy engine and policy lifecycle workstate:agent-readyApproved for agent implementationstate:in-progressWork is currently in progresstopic:compatibilityCompatibility-related worktopic:testing

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions