Skip to content

feat(server): add workspace secrets for shared refresh material - #5699

Open
mrunalp wants to merge 6 commits into
mainfrom
feat/5563-workspace-secrets/mrunalp
Open

mrunalp wants to merge 6 commits into
mainfrom
feat/5563-workspace-secrets/mrunalp

Conversation

@mrunalp

@mrunalp mrunalp commented Nov 18, 2026

Copy link
Copy Markdown
Collaborator

Summary

Add workspace secrets: named, workspace-scoped values that provider refresh configuration can reference as minting material, so one shared OAuth client secret rotates for every provider that uses it. OpenShell never injects them into sandboxes. The first commit adds the design RFC; the rest implement it.

Related Issue

Closes #5563

Changes

  • RFC (rfc/NNNN-workspace-secrets/): design, threat model, activation and rollback. The RFC number is still a placeholder until one is assigned on Support shared non-injectable secret references and authorized control-plane reads #5563.
  • Secret resource: CreateSecret/GetSecret/ListSecrets/UpdateSecret/DeleteSecret.
    • Values are stored through the credential issuer under a new WorkspaceSecret owner kind and never returned by Get or List.
    • Each secret has immutable, normalized allowed_endpoints.
    • Updates stage a new handle and delete the old one. Deletes tombstone the record, and the refresh worker tick sweeps unfinished cleanup.
    • The private record lives in a new openshell.storage.secret.v1 package; the frozen storage.v1 schema is unchanged.
  • Activation: creating secrets and referencing them requires the default-off enable_workspace_secrets setting and a workspace_secrets_protocol membership capability, reusing the sandbox-update check. Workspace deletion is blocked while secrets exist.
  • Refresh references: ConfigureProviderRefreshRequest.material_secrets (key → secret name).
    • Each key must also be listed in secret_material_keys, so older gateways reject the request instead of ignoring it.
    • Only secret material can be referenced, never refresh_token.
    • The effective token endpoint must be one the secret allows. The minter re-checks it before sending and refuses redirects for secret-bearing requests.
    • Bindings live in a refresh-state annotation, which older gateways preserve.
    • Mints read the current value and re-read the record once if an update raced them.
    • DeleteSecret refuses while a refresh references the secret.
    • New InlineProviderRefreshSecrets copies values into provider-owned material and keeps a rotated refresh token.
    • ProviderCredentialRefreshStatus.material_secrets reports the references.
  • RevealSecret: off unless enable_secret_reveal is set. The handler accepts operator mTLS, or OIDC workspace admins with the literal secret:reveal scope on a scope-enforcing gateway; openshell:all, unscoped OIDC, user mTLS, and local-dev identities are rejected. Every call is audited.
  • CLI:
    • New openshell secret create|update|get|list|delete, which reads values from --value-env or --value-file.
    • provider refresh configure --material-secret KEY=SECRET.
    • provider refresh inline-secrets.
  • Docs: provider refresh, gateway configuration (enable_workspace_secrets, enable_secret_reveal, activation and rollback), workspace scopes, and the openshell-cli skill.

Not in this PR:

Release Notes

Operators can store a shared secret once with openshell secret create and reference it from many providers' refresh configuration with --material-secret. Updating the secret reaches every provider at its next refresh. The feature is off until a gateway sets enable_workspace_secrets.

Testing

  • Checks appropriate to the affected code and behavior pass
    • cargo clippy --workspace --all-targets -D warnings, cargo fmt, buf lint, mise run sdk:ts:ci, and markdownlint on the changed docs and RFC.
    • Unit and integration tests for openshell-server, openshell-credential-issuer, openshell-core, openshell-cli, openshell-sdk, and openshell-gateway-interceptors.
    • The Unix-socket tests in openshell-server and openshell-core fail inside my local sandbox; I reran them outside it and they pass.
    • Not run: ssh_identity::default_credential_store_persists_key_across_runtime_reconstruction, which writes under ~/.local/state.
    • Not run: the Fern docs build.
  • Unit tests added/updated
    • The full refresh lifecycle against a mock token endpoint: mint, rotate the secret, mint with the new value, delete guard, inline, mint again.
    • Rejection rules: unlisted key, inline duplicate, non-secret key, refresh_token, missing secret, disallowed endpoint, tenant override, and activation off.
    • A redirect from an approved endpoint never reaches the target.
    • A mint racing a value update re-reads the record.
    • A lost binding fails closed.
    • Reveal principal matrix.
    • Workspace-delete guard.
    • The membership capability check.
    • CLI flag wiring.
  • E2E tests added/updated
    • The RFC's tests against the previous release binary and its Postgres activation path aren't covered yet. SQLite skips the membership check by design.

Checklist

  • Follows Conventional Commits
  • Commits are signed off (DCO)
  • Architecture docs updated (if applicable)

Propose workspace-scoped secrets that provider refresh configuration can
reference, so one shared OAuth client secret rotates for every provider.
Refs #5563.

Signed-off-by: Mrunal Patel <mrunalp@gmail.com>
Add a workspace-scoped Secret resource whose value is stored through the
credential issuer under a new WorkspaceSecret owner kind and is never
returned by Get or List. Each secret declares immutable, normalized token
endpoints it may be sent to.

Creation is gated behind the default-off enable_workspace_secrets setting
and a workspace-secrets membership capability, reusing the sandbox-update
activation check. Updates stage a new value and delete the superseded
handle; deletes tombstone the record and a periodic sweep retries any
backend cleanup. Workspace deletion is blocked while secrets exist.

Refs #5563

Signed-off-by: Mrunal Patel <mrunalp@gmail.com>
Let ConfigureProviderRefresh take secret material from a workspace secret
by name. The gateway binds each key to the secret's immutable ID in a
refresh-state annotation, which older gateways preserve, and requires the
key in secret_material_keys so those gateways reject the request and
refuse to mint without it.

Only secret material can be referenced, never a key the minter rotates
per provider. The token endpoint a mint will call must be one the secret
allows; the minter re-checks it before sending and refuses redirects for
requests carrying a workspace secret. Mints read the secret's current
value and re-read the record once if an update raced them.

DeleteSecret refuses while a refresh references the secret, and the new
InlineProviderRefreshSecrets RPC copies referenced values into
provider-owned material without disturbing a rotated refresh token.

Refs #5563

Signed-off-by: Mrunal Patel <mrunalp@gmail.com>
Return a workspace secret's value to operators, or to OIDC workspace
admins whose token carries the literal secret:reveal scope on a gateway
that enforces scopes. openshell:all, unscoped OIDC gateways, user mTLS
certificates, and local development identities are rejected in the
handler, independent of middleware scope handling. The RPC is disabled
unless enable_secret_reveal is set, and every call is audited.

Group the workspace secret settings under WorkspaceSecretsConfig.

Refs #5563

Signed-off-by: Mrunal Patel <mrunalp@gmail.com>
Add openshell secret create, update, get, list, and delete. Values come
from an environment variable or a file and are never printed. Add
--material-secret to provider refresh configure, which also lists each
referenced key in secret_material_keys, and provider refresh
inline-secrets for unwinding references.

Refs #5563

Signed-off-by: Mrunal Patel <mrunalp@gmail.com>
Describe shared secret material for provider refresh, the
enable_workspace_secrets and enable_secret_reveal gateway settings with
activation and rollback steps, and the new secret scopes.

Refs #5563

Signed-off-by: Mrunal Patel <mrunalp@gmail.com>
@copy-pr-bot

copy-pr-bot Bot commented Nov 18, 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.

@github-actions github-actions Bot added the state:accepted A maintainer decided OpenShell should pursue this issue label Nov 18, 2026
@github-actions

Copy link
Copy Markdown

@mrunalp
mrunalp marked this pull request as ready for review November 18, 2026 14:53

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

state:accepted A maintainer decided OpenShell should pursue this issue

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support shared non-injectable secret references and authorized control-plane reads

1 participant