mirror of https://github.com/openclaw/openclaw.git synced 2026-03-12 23:40:45 +00:00

Files

Josh Lehman 8525fd94ea docs: sync Feishu secretref credential matrix

## Summary

- Problem: `src/secrets/target-registry.test.ts` fails on latest `main` because the runtime registry includes Feishu `encryptKey` paths that the docs matrix and surface reference omit.
- Why it matters: the docs/runtime sync guard currently blocks prep and merge work for unrelated PRs, including `#25558`.
- What changed: regenerated the secretref credential matrix and updated the surface reference to include both Feishu `encryptKey` paths.
- What did NOT change (scope boundary): no runtime registry behavior, config semantics, or channel handling changed.

## Change Type (select all)

- [x] Bug fix
- [ ] Feature
- [ ] Refactor
- [x] Docs
- [ ] Security hardening
- [ ] Chore/infra

## Scope (select all touched areas)

- [ ] Gateway / orchestration
- [ ] Skills / tool execution
- [ ] Auth / tokens
- [ ] Memory / storage
- [x] Integrations
- [ ] API / contracts
- [ ] UI / DX
- [ ] CI/CD / infra

## Linked Issue/PR

- Closes #
- Related #25558

## User-visible / Behavior Changes

None.

## Security Impact (required)

- New permissions/capabilities? `No`
- Secrets/tokens handling changed? `No`
- New/changed network calls? `No`
- Command/tool execution surface changed? `No`
- Data access scope changed? `No`
- If any `Yes`, explain risk + mitigation:

## Repro + Verification

### Environment

- OS: macOS
- Runtime/container: Node.js repo checkout
- Model/provider: N/A
- Integration/channel (if any): Feishu docs/runtime registry sync
- Relevant config (redacted): none

### Steps

1. Check out latest `main` before this change.
2. Run `./node_modules/.bin/vitest run --config vitest.unit.config.ts src/secrets/target-registry.test.ts`.
3. Apply this docs-only sync change and rerun the same command.

### Expected

- The target registry stays in sync with the generated docs matrix and the test passes.

### Actual

- Before this change, the test failed because `channels.feishu.encryptKey` and `channels.feishu.accounts.*.encryptKey` were missing from the docs artifacts.

## Evidence

Attach at least one:

- [x] Failing test/log before + passing after
- [ ] Trace/log snippets
- [ ] Screenshot/recording
- [ ] Perf numbers (if relevant)

## Human Verification (required)

What you personally verified (not just CI), and how:

- Verified scenarios: confirmed the failure on plain latest `main`, applied only these docs entries in a clean bootstrapped worktree, and reran `./node_modules/.bin/vitest run --config vitest.unit.config.ts src/secrets/target-registry.test.ts` to green.
- Edge cases checked: verified both top-level Feishu `encryptKey` and account-scoped `encryptKey` paths are present in the matrix and surface reference.
- What you did **not** verify: full repo test suite and CI beyond the targeted regression.

## Review Conversations

- [x] I replied to or resolved every bot review conversation I addressed in this PR.
- [x] I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

## Compatibility / Migration

- Backward compatible? `Yes`
- Config/env changes? `No`
- Migration needed? `No`
- If yes, exact upgrade steps:

## Failure Recovery (if this breaks)

- How to disable/revert this change quickly: revert this commit.
- Files/config to restore: `docs/reference/secretref-user-supplied-credentials-matrix.json` and `docs/reference/secretref-credential-surface.md`
- Known bad symptoms reviewers should watch for: the target-registry docs sync test failing again for missing Feishu `encryptKey` entries.

## Risks and Mitigations

- Risk: the markdown surface reference could drift from the generated matrix again in a later credential-shape change.
  - Mitigation: `src/secrets/target-registry.test.ts` continues to guard docs/runtime sync.

2026-03-12 08:18:13 -07:00

5.0 KiB

Raw Permalink Blame History

summary, read_when, title

summary

read_when

title

Canonical supported vs unsupported SecretRef credential surface

Verifying SecretRef credential coverage

Auditing whether a credential is eligible for `secrets configure` or `secrets apply`

Verifying why a credential is outside the supported surface

SecretRef Credential Surface

SecretRef credential surface

This page defines the canonical SecretRef credential surface.

Scope intent:

In scope: strictly user-supplied credentials that OpenClaw does not mint or rotate.
Out of scope: runtime-minted or rotating credentials, OAuth refresh material, and session-like artifacts.

Supported credentials

`openclaw.json` targets (`secrets configure` + `secrets apply` + `secrets audit`)

models.providers.*.apiKey
models.providers.*.headers.*
skills.entries.*.apiKey
agents.defaults.memorySearch.remote.apiKey
agents.list[].memorySearch.remote.apiKey
talk.apiKey
talk.providers.*.apiKey
messages.tts.elevenlabs.apiKey
messages.tts.openai.apiKey
tools.web.fetch.firecrawl.apiKey
tools.web.search.apiKey
tools.web.search.gemini.apiKey
tools.web.search.grok.apiKey
tools.web.search.kimi.apiKey
tools.web.search.perplexity.apiKey
gateway.auth.password
gateway.auth.token
gateway.remote.token
gateway.remote.password
cron.webhookToken
channels.telegram.botToken
channels.telegram.webhookSecret
channels.telegram.accounts.*.botToken
channels.telegram.accounts.*.webhookSecret
channels.slack.botToken
channels.slack.appToken
channels.slack.userToken
channels.slack.signingSecret
channels.slack.accounts.*.botToken
channels.slack.accounts.*.appToken
channels.slack.accounts.*.userToken
channels.slack.accounts.*.signingSecret
channels.discord.token
channels.discord.pluralkit.token
channels.discord.voice.tts.elevenlabs.apiKey
channels.discord.voice.tts.openai.apiKey
channels.discord.accounts.*.token
channels.discord.accounts.*.pluralkit.token
channels.discord.accounts.*.voice.tts.elevenlabs.apiKey
channels.discord.accounts.*.voice.tts.openai.apiKey
channels.irc.password
channels.irc.nickserv.password
channels.irc.accounts.*.password
channels.irc.accounts.*.nickserv.password
channels.bluebubbles.password
channels.bluebubbles.accounts.*.password
channels.feishu.appSecret
channels.feishu.encryptKey
channels.feishu.verificationToken
channels.feishu.accounts.*.appSecret
channels.feishu.accounts.*.encryptKey
channels.feishu.accounts.*.verificationToken
channels.msteams.appPassword
channels.mattermost.botToken
channels.mattermost.accounts.*.botToken
channels.matrix.password
channels.matrix.accounts.*.password
channels.nextcloud-talk.botSecret
channels.nextcloud-talk.apiPassword
channels.nextcloud-talk.accounts.*.botSecret
channels.nextcloud-talk.accounts.*.apiPassword
channels.zalo.botToken
channels.zalo.webhookSecret
channels.zalo.accounts.*.botToken
channels.zalo.accounts.*.webhookSecret
channels.googlechat.serviceAccount via sibling serviceAccountRef (compatibility exception)
channels.googlechat.accounts.*.serviceAccount via sibling serviceAccountRef (compatibility exception)

`auth-profiles.json` targets (`secrets configure` + `secrets apply` + `secrets audit`)

profiles.*.keyRef (type: "api_key")
profiles.*.tokenRef (type: "token")

Notes:

Auth-profile plan targets require agentId.
Plan entries target profiles.*.key / profiles.*.token and write sibling refs (keyRef / tokenRef).
Auth-profile refs are included in runtime resolution and audit coverage.
For SecretRef-managed model providers, generated agents/*/agent/models.json entries persist non-secret markers (not resolved secret values) for apiKey/header surfaces.
Marker persistence is source-authoritative: OpenClaw writes markers from the active source config snapshot (pre-resolution), not from resolved runtime secret values.
For web search:
- In explicit provider mode (tools.web.search.provider set), only the selected provider key is active.
- In auto mode (tools.web.search.provider unset), only the first provider key that resolves by precedence is active.
- In auto mode, non-selected provider refs are treated as inactive until selected.

Unsupported credentials

Out-of-scope credentials include:

commands.ownerDisplaySecret
channels.matrix.accessToken
channels.matrix.accounts.*.accessToken
hooks.token
hooks.gmail.pushToken
hooks.mappings[].sessionKey
auth-profiles.oauth.*
discord.threadBindings.*.webhookToken
whatsapp.creds.json

Rationale:

These credentials are minted, rotated, session-bearing, or OAuth-durable classes that do not fit read-only external SecretRef resolution.

5.0 KiB Raw Permalink Blame History