Operations (Contract)

Opaque exposes operations, not raw secret values.

v1 transport is local only:

• opaque (CLI) -> Unix domain socket -> opaqued (daemon)

For MCP-aware tools (Claude Code), opaque-mcp provides a stdio-based MCP server that exposes Safe operations as tools. See MCP integration.

Safety Classes

Class	Meaning	Agent Access
SAFE	Uses secrets internally and must not return them	Allowed (with policy + approvals)
SENSITIVE_OUTPUT	Output may contain credential-like data	Denied for agents unless explicitly allowlisted in policy
REVEAL	Returns plaintext secrets	Never (hard-blocked in v1)

Secret Ref Schemes

Operations that accept value_ref or *_token_ref support:

• env:NAME
• keychain:service/account
• profile:<name>:<key>
• onepassword:<vault>/<item>/<field>
• bitwarden:<project>/<key> or bitwarden:<secret-id>
• vault:<path>#<field>
• azure:<vault>/<secret> or azure:<vault>/<secret>/<version>
• gcp:<project>/<secret> or gcp:<project>/<secret>/<version>

Implemented Operations

test.noop (SAFE)

No inputs.

Result:

• { "status": "ok" }

sandbox.exec (SENSITIVE_OUTPUT)

Runs a command in a platform sandbox using an execution profile.

Inputs (via opaque exec --profile <name> -- <cmd...>):

• profile: profile name (loads ~/.opaque/profiles/<name>.toml)
• command: command argv array

Result:

• exit_code: i32
• duration_ms: u64
• stdout_length: u64
• stderr_length: u64
• stdout: string (captured; may be empty)
• stderr: string (captured; may be empty)
• truncated: bool (true when capture was capped)

Notes:

• The current implementation returns captured stdout/stderr (and the CLI prints it). Treat this as SENSITIVE_OUTPUT: agent clients should not be allowed by default, and sandboxed commands must not print secret material.

github.set_actions_secret (SAFE)

Sets a GitHub Actions secret using GitHub's public-key encryption.

Supports both:

• repo-level Actions secrets
• environment-level Actions secrets

Inputs:

• repo: owner/repo
• secret_name: secret name (ex: AWS_ACCESS_KEY_ID)
• value_ref: secret reference (ex: keychain:opaque/my-token)
• optional: github_token_ref: GitHub token ref (default: keychain:opaque/github-pat for pat mode, keychain:opaque/github-oauth-token for oauth mode)
• optional: github_auth_mode: "pat" | "oauth" (default: pat)
• optional: environment: when set, writes an Actions environment secret instead of a repo secret

Result:

• status: created | updated
• repo
• optional: environment
• secret_name
• auth_mode: pat | oauth

Notes:

• Never return the secret value or its ciphertext.
• For GitHub Enterprise Server or local testing, opaqued honors OPAQUE_GITHUB_API_URL as the API base URL.
• github_auth_mode controls token-ref defaults; GitHub API calls use Authorization: Bearer.

github.set_codespaces_secret (SAFE)

Sets a GitHub Codespaces secret.

Supports both:

• user-level Codespaces secrets
• repo-level Codespaces secrets

Inputs:

• secret_name
• value_ref
• optional: repo (owner/repo) (when set, creates a repo-level Codespaces secret)
• optional: github_token_ref (default: keychain:opaque/github-pat for pat mode, keychain:opaque/github-oauth-token for oauth mode)
• optional: github_auth_mode: "pat" | "oauth" (default: pat)
• optional: selected_repository_ids (user-level only; when omitted, GitHub defaults apply)

Result:

• status: created | updated
• secret_name
• optional: repo (repo-level)
• optional: scope: "user" (user-level)
• auth_mode: pat | oauth

Notes:

• Never return the secret value or its ciphertext.

github.set_dependabot_secret (SAFE)

Sets a GitHub Dependabot repository secret.

Inputs:

• repo: owner/repo
• secret_name
• value_ref
• optional: github_token_ref (default: keychain:opaque/github-pat for pat mode, keychain:opaque/github-oauth-token for oauth mode)
• optional: github_auth_mode: "pat" | "oauth" (default: pat)

Result:

• status: created | updated
• repo
• secret_name
• auth_mode: pat | oauth

Notes:

• Never return the secret value or its ciphertext.

github.set_org_secret (SAFE)

Sets a GitHub Actions organization secret.

Inputs:

• org
• secret_name
• value_ref
• optional: github_token_ref (default: keychain:opaque/github-pat for pat mode, keychain:opaque/github-oauth-token for oauth mode)
• optional: github_auth_mode: "pat" | "oauth" (default: pat)
• optional: visibility: "all" | "private" | "selected" (default: "private")
• optional: selected_repository_ids (when visibility = "selected")

Result:

• status: created | updated
• org
• secret_name
• auth_mode: pat | oauth

Notes:

• Never return the secret value or its ciphertext.

gitlab.set_ci_variable (SAFE)

Sets a GitLab CI/CD variable for a project.

Inputs:

• project: project path or ID (ex: group/project)
• key: variable key (ex: DATABASE_URL)
• value_ref: secret reference (ex: keychain:opaque/db-url)
• optional: gitlab_token_ref: GitLab token ref (default: keychain:opaque/gitlab-pat for pat mode, keychain:opaque/gitlab-oauth-token for oauth mode)
• optional: gitlab_auth_mode: "pat" | "oauth" (default: pat)
• optional: environment_scope
• optional: protected: boolean
• optional: masked: boolean
• optional: raw: boolean
• optional: variable_type: "env_var" | "file" (default: "env_var")

Result:

• status: created | updated
• project
• key
• optional: environment_scope
• optional: protected
• optional: masked
• optional: raw
• optional: variable_type
• auth_mode: pat | oauth

Notes:

• Never returns variable values.
• Supports GitLab self-managed or alternate API hosts via OPAQUE_GITLAB_API_URL.
• pat mode sends PRIVATE-TOKEN; oauth mode sends Authorization: Bearer.

azure.list_secrets (SAFE)

Lists Azure Key Vault secret metadata.

Inputs: none.

Result:

• secrets: array of { name, enabled }

azure.list_keys (SAFE)

Lists Azure Key Vault key metadata.

Inputs: none.

Result:

• keys: array of { name, enabled }

azure.list_certificates (SAFE)

Lists Azure Key Vault certificate metadata.

Inputs: none.

Result:

• certificates: array of { name, enabled }

azure.get_secret (REVEAL)

Reads a specific Azure Key Vault secret value.

Inputs:

• name
• optional: version

Result:

• name
• value (plaintext)

Notes:

• Hard-blocked for agent workflows by default policy (reveal operation).

azure.set_secret (SAFE)

Writes an Azure Key Vault secret value from a secure reference.

Inputs:

• name
• value_ref

Result:

• name
• status (ok)

Notes:

• Never returns secret values.
• Requires Azure configuration in the daemon environment: OPAQUE_AZURE_VAULT_URL, OPAQUE_AZURE_TENANT_ID, OPAQUE_AZURE_CLIENT_ID, OPAQUE_AZURE_CLIENT_SECRET.

gcp.list_secrets (SAFE)

Lists GCP Secret Manager secret metadata for a project.

Inputs:

• project

Result:

• project
• secrets: array of { name }

gcp.get_secret (SAFE)

Reads GCP Secret Manager secret metadata (no value).

Inputs:

• project
• secret_id

Result:

• name
• create_time

gcp.access_secret_version (REVEAL)

Reads a specific GCP secret version value.

Inputs:

• project
• secret_id
• optional: version (default: latest)

Result:

• project
• secret_id
• version
• value (plaintext)

Notes:

• Hard-blocked for agent workflows by default policy (reveal operation).

gcp.create_secret (SAFE)

Creates a new secret in GCP Secret Manager.

Inputs:

• project
• secret_id

Result:

• name
• create_time

gcp.add_secret_version (SAFE)

Adds a new version to an existing GCP secret from a secure reference.

Inputs:

• project
• secret_id
• value_ref

Result:

• version
• state

Notes:

• Never returns secret values.
• Requires GCP auth configured via OPAQUE_GCP_ACCESS_TOKEN or OPAQUE_GCP_SERVICE_ACCOUNT_KEY.

onepassword.list_vaults (SAFE)

Lists accessible 1Password vaults (names + descriptions only).

Result:

• vaults: array of { name, description }

Notes:

• Safe for agents if your policy allows it; does not return vault IDs or any secret values.

onepassword.list_items (SAFE)

Lists item titles in a vault (no field values).

Inputs:

• vault: vault name

Result:

• vault: vault name
• items: array of { title, category }

Notes:

• Safe for agents if your policy allows it; does not return item IDs or any secret values.

onepassword.read_field (REVEAL)

Reads a single field value from a 1Password item.

Inputs:

• vault: vault name
• item: item title
• field: field label

Result:

• vault
• item
• field
• value (plaintext)

Notes:

• This violates the core v1 rule "LLMs get operations, not values". It should not be enabled for agent workflows. If kept at all, it should be hard-blocked or reserved for interactive human-only flows with explicit friction.

bitwarden.list_projects (SAFE)

Lists accessible Bitwarden Secrets Manager projects.

Inputs: none.

Result:

• projects: array of { name, id }

Notes:

• Safe for agents if your policy allows it; returns project metadata only.

bitwarden.list_secrets (SAFE)

Lists secret names in a Bitwarden project (no values).

Inputs:

• optional: project: project name (filters results)

Result:

• secrets: array of { key, id, project }

Notes:

• Safe for agents if your policy allows it; does not return secret values.

bitwarden.read_secret (REVEAL)

Reads a single secret value from Bitwarden Secrets Manager.

Inputs:

• id: secret UUID, or
• project + key: project name and secret key

Result:

• key
• value (plaintext)

Notes:

• Hard-blocked in v1. Returns plaintext secrets — should not be enabled for agent workflows. Reserved for interactive human-only flows with explicit friction.

Deferred Specs (Not Implemented In v1)

These are design placeholders and should not be treated as supported operations in v1:

• k8s.set_secret
• k8s.apply_manifest
• aws.call
• http.request_with_auth