Tell the agent whether each secret is personal or org-shared

Open
#723 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

  • #1257 by @juanmichelini — closed without merging
  • #1292 by @juanmichelini — closed without merging

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
28/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
python
Domain
backend, security

Research direction

Start in openhands/app_server/integrations/provider.py (CustomSecret) and storage/saas_secrets_store.py (SaasSecretsStore.load(), where scope must be set after _decrypt_kwargs), then read get_secrets() in auth_user_context and integrations/resolver_context. Done means shared entries load as ORGANIZATION, system credentials are PERSONAL, and unit tests cover load() scope assignment. The work is blocked on software-agent-sdk#5672, so don't start until that release ships.

Written by the indexing model from the issue text.

Description

enhancement

Summary

When a conversation has both personal and org-shared secrets, the agent can't tell which is which, so it may act as the wrong identity. Use the new SDK scope / scope_description fields (OpenHands/software-agent-sdk#5672) to group secrets as personal or organization, with guidance on when to use each.

Problem

Org-shared secrets are meant to be service-account credentials: a bot Linear key, a GitHub bot token, a Slack bot token. A shared key is a different identity from the user, often with different permissions. Choosing between a personal key and a shared one decides who is acting, and the agent can't make that choice if it can't tell them apart.

Example, with everything set up correctly:

An admin adds a Linear service-account key ("OpenHands Bot") as an org-shared secret for automation and team triage. A member also has their own personal Linear key. They ask the agent to "file tickets for the bugs we found." The agent sees two Linear keys with identical descriptions and picks the first one. The tickets are created by OpenHands Bot: they're missing from the member's "Created by me" view, replies notify the bot, and the audit trail doesn't show who asked.

The same pattern applies elsewhere:

  • GitHub: a PR opened with a shared bot token is authored by the bot, so the person who asked for the change can approve it themselves.
  • Permissions: a broader service account lets the agent read or change things the user can't; a narrower one fails, and the agent may wrongly report that the user lacks access.
  • Slack: the choice decides whether a message is posted as the person or as the bot.

Users already try to work around this by writing "use only when directed"-style notes into secret descriptions, which is inconsistent and depends on each secret's creator.

Why Agent Profiles don't cover this

Agent Profiles decide which secrets a conversation may use (secret_refs). Scope labels tell the agent whose identity each of those secrets is. Both are needed:

  1. Mixed lists remain. The default profile allows all secrets. A "personal only" default helps only until someone opts in to shared secrets, and any profile that legitimately needs both (a personal Linear key plus an org Datadog key) brings the ambiguity back.
  2. A secret name doesn't say whose secret it is. When personal and shared secrets are merged, the personal one gets the bare name and the shared one becomes _2. In an org-shared profile allowing LINEAR_API_KEY, that name means the member's own key if they have one, and the bot's key if they don't. If they add a personal key later, the shared key is renamed and silently drops out of the profile. Labels report what each name actually resolved to in this conversation.
  3. Transparency. Labels let the agent say "I filed these as OpenHands Bot using the org's shared key," or ask which key to use, instead of the user finding out from the results.
  4. No configuration needed. Labels help every conversation, including those of users who never set up a profile.

This is guidance to the model, not access control. Restricting which secrets reach a conversation remains the job of profiles and permissions.

Proposed implementation

  1. Carry the scope through CustomSecret (openhands/app_server/integrations/provider.py): add scope: CustomSecretScope = PERSONAL. Move CustomSecretScope here from secrets/secrets_models.py and re-export it there, so the two modules don't import each other.
  2. SaasSecretsStore.load() (storage/saas_secrets_store.py): mark shared entries as ORGANIZATION. Set the scope after _decrypt_kwargs, which decrypts every leaf value in the dict. store() reads only secret and description, so writes are unaffected.
  3. Build the SDK secrets with scopes in auth_user_context.get_secrets() (covers the regular and ACP conversation paths) and integrations/resolver_context.get_secrets(), which also drops description today. That looks like a bug; fix it here too.
  4. Mark the user's own system credentials as personal: git provider tokens (*_TOKEN in _setup_secrets_for_git_providers and the ACP path), integration secrets such as JIRA_DC_TOKEN, and OPENHANDS_API_KEY. Otherwise they'd land in the unscoped group.
  5. Scope descriptions (constants):
    • personal: "The user's own credentials. Actions are attributed to the user and limited to the user's permissions. Use these when acting on the user's behalf."
    • organization: "Shared service-account credentials provided by the organization. Actions are attributed to the shared account, not the user, and may have different permissions. Use these only when the task calls for the shared identity (for example team automation) or no personal credential fits, and tell the user when you do."
  6. Bump the openhands-sdk / openhands-agent-server pins to the release that includes the SDK change.

Acceptance criteria

  • A conversation with personal and org-shared secrets shows them under separate personal and organization groups in <CUSTOM_SECRETS>, each with its description.
  • Git provider, integration and OPENHANDS_API_KEY secrets appear under personal.
  • A conversation with only personal secrets shows a single personal group.
  • The ACP and resolver conversation paths carry the same scopes; the resolver path also passes description.
  • Unit tests cover SaasSecretsStore.load() scope assignment (including names suffixed after a collision) and secret construction in auth_user_context.

Rollout

Blocked on OpenHands/software-agent-sdk#5672. Ship the SDK release first, then this change. Both fields are optional and ignored by older agent-servers, so there's no ordering hazard.


Idea from @jpshackelford.

This issue was created by an AI agent (OpenHands) on behalf of John-Mason Shackelford.

Dominant language
Python
Stars
9
Forks
17
Avg merge
1d 7h
Merged PRs (30d)
396

Getting set up

  • Ships a Dockerfile or Docker Compose file
  • Has a pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from OpenHands/enterprise

All issues in OpenHands/enterprise

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.