Skip to content

feat: workspace secrets (OpenShell RFC 0024) — manage secrets and reference them from provider refresh #143

Open

Description

@Gkrumbach07

Upstream NVIDIA/OpenShell#5699 (merged 2026-11-19, closes ai-openshell/openshell#5563, design in RFC 0024) adds workspace secrets: named, workspace-scoped values that a provider's refresh configuration can reference as minting material, so one shared OAuth client secret is stored once and rotates for every provider that uses it. OpenShell never injects a secret into a sandbox, and Get/List never return its value.

The console should let workspace admins manage them and reference them from Configure refresh.

What the gateway adds

New RPCs on openshell.v1.OpenShell:

RPC Auth Notes
CreateSecret bearer, secret:write, workspace admin name, description, value (secret), optional refresh_use.allowed_endpoints (immutable; without it the secret is reveal-only and cannot back a refresh), labels, request_id
GetSecret / ListSecrets bearer, secret:read, workspace user metadata only: metadata, description, refresh_use, value_update_time. List is paginated, takes label_selector
UpdateSecret bearer, secret:write, workspace admin merge: optional value, optional description, labels replaces the whole set when present, expected_resource_version
DeleteSecret bearer, secret:write, workspace admin returns a DeletionOutcome; refused while a refresh references the secret
InlineProviderRefreshSecrets bearer, provider:write, workspace admin copies the referenced secrets into provider-owned material for one credential and drops the references
RevealSecret operator (mTLS) only off unless enable_secret_reveal. Not reachable by an OIDC user, so not for the console

Changes to existing messages:

  • ConfigureProviderRefreshRequest.material_secrets (material key → secret name). Every key must also be in secret_material_keys (so older gateways reject instead of ignoring), only secret material can be referenced (never refresh_token), and the effective token endpoint must be one the secret allows.
  • ProviderCredentialRefreshStatus.material_secrets reports the references.

Activation: off until the gateway sets enable_workspace_secrets, plus a workspace_secrets_protocol membership capability. Workspace deletion is blocked while secrets exist.

Proposed scope

BFF (backend/pkg/handlers, services, models)

  • GET/POST /api/v1/workspaces/{workspace}/secrets, GET/PATCH/DELETE .../secrets/{name}, mirroring the gateway messages. The value is write-only: never in a response, and UpdateSecret sends only what the request names (hard fact 8's rule for providers applies).
  • ConfigureProviderRefreshBody gains materialSecrets; the refresh status DTO gains materialSecrets.
  • POST .../providers/{name}/refresh/{credentialKey}/inline-secrets for InlineProviderRefreshSecrets.
  • Delete through models.FromSDKDeletion.
  • No RevealSecret route (operator-only, and secrets never reach the browser).

UI

  • A Secrets page under the workspace (admin: create, edit value/description/labels, delete; user: read-only list). Create form makes the "allowed token endpoints" choice explicit and says it cannot change later; reveal-only vs. refresh-usable is shown on the list.
  • Configure refresh dialog: for each secret material key, choose "enter a value" or "use workspace secret", filtered to secrets whose allowed_endpoints include the effective token endpoint. Send the key in both materialSecrets and secretMaterialKeys.
  • Provider detail: show which credentials draw on which secrets, and an "Inline secrets" action.
  • Delete dialog explains a refusal when a refresh still references the secret; workspace delete explains the block when secrets exist.
  • Gate on the gateway answering (feature off → FailedPrecondition/Unimplemented): hide or explain, don't error the page.

Tests: handler table tests, mock SDK doubles, and a compat test once the pinned gateway has it (vary the workspace, hard fact 17).

Blocked on

  1. An OpenShell release. It merged after v0.1.9 and isn't in any tag yet; main pins 0.1.6. Per ADR 0005 this goes on the bump/openshell-X.Y.Z branch of the first release that carries it (or a prep branch from Follow upstream on the pre-release), not main.
  2. Go SDK coverage. The PR notes the Go and Python SDK updates are separate. ai-openshell/sdk-go needs Secrets() (Create/Get/List/Update/Delete), MaterialSecrets on the refresh configure request and status, and InlineProviderRefreshSecrets. No new raw gRPC call in the BFF for this; wait for the SDK (ADR 0003, decision 4).

Out of scope upstream (for now)

aws_sts_assume_role references (rejected until the STS client enforces endpoint/redirect rules), client_secret_basic (ai-openshell/openshell#5663), and OIDC user access to reveal.

Activity

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

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions