secrets

Files (4)

• SKILL.md
• delete.ts · assets/
• list-keys.ts · assets/
• set.ts · assets/

SKILL.md (first lines)

# Scoped secrets

Manage OrgOps scoped secrets. Agents can **write** key-value pairs, **list** secret keys (not values), and **delete** keys. Secret values are never returned to the agent; they are only injected as environment variables when the runner executes skills or calls the LLM.

## Secure secret collection in chat

When you need a user to provide a secret, **do not ask them to paste the secret value in plain chat text**.

Instead, return a single HTML component that the UI can render as a secure input form:

```html
<orgops-secret-input package="llm" key="OPENAI_API_KEY" label="Set OpenAI API key" submit-label="Save secret" description="This value is sent directly to the secrets API and is not posted as a chat message."></orgops-secret-input>
```

Rules:

- Return only the component as the full message body (no surrounding markdown/code fences/text).
- Use `package` and `key` when known; users can still edit values in the form before submit.
- Never echo back secret values.
- If this component is available, prefer it over requesting plain-text secrets.

## Usage

All commands require `ORGOPS_RUNNER_TOKEN` and use `ORGOPS_API_URL` (default `http://localhost:8787`).

### Set a secret (legacy package helper)

```bash
node --import tsx {baseDir}/assets/set.ts -- <package> <key> <value>
```

Example: store OpenAI key for the legacy `llm` package scope:

```bash
ORGOPS_RUNNER_TOKEN=... node --import tsx {baseDir}/assets/set.ts -- llm OPENAI_API_KEY sk-...
```

### List secret keys

Returns key names only (and package), never values.

```bash
node --import tsx {baseDir}/assets/list-keys.ts -- [package]
```

Examples:

```bash
node --import tsx {baseDir}/assets/list-keys.ts --           # all packages
node --import tsx {baseDir}/assets/list-keys.ts -- llm       # only keys for package "llm"
```

### Delete a secret

```bash
node --import tsx {baseDir}/assets/delete.ts -- <package> <key>
```

Example:

```bash
node --import tsx {baseDir}/assets/delete.ts -- llm OPENAI_API_KEY
```

## Package names

Use a logical package name that matches how the secret is used, e.g. `llm` for `OPENAI_API_KEY`. Package scope is legacy compatibility.

## Runtime scopes

Runtime env injection resolves matching keys in this order:

1. `private` (agent-specific; `scopeId=<agentName>`)
2. `team` (`scopeId=<teamId>` from the active channel context)
3. `public`
4. `package` (legacy)

For provider credentials (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`), runtime execution uses the resolved scoped secret and does not fall back to host process env.

## Sending sensitive info back to humans

When a response must include sensitive content (passwords, tokens, private keys, reset links), send it as a `message.created` event with `payload.sensitive` instead of plain chat text.

Example payload pattern:

```json
{
  "type": "message.created",
  "channelId": "<channel-id>",
  "source": "agent:<name>",
  "payload": {
    "text": "Sensitive content available. Reveal with password.",
    "sensitive": {
      "plaintext": "TOKEN=...",
      "hint": "Temporary credential for staging"
    }
  }
}
```

Rules:

- Keep `payload.text` as a safe preview only (no secrets).
- Put secret content in `payload.sensitive.plaintext`; API encrypts it before storage.
- Never repeat revealed secret text in later messages unless explicitly requested.

From camplight/orgops, Apache-2.0.

More from camplight/orgops