ChatGPTClaudeGrok / X / CursorGemini

DSH plugin credentials: refs, records, and platform sessions

Plugin DevelopmentPublished 2026-11-12Author: DeepSeek Plugin Market
DSH pluginDeepSeek HarnessCredentialsCredentialRefPlatformSession
DSH plugin credentials: two key spaces, per-operation resolution as hot reload, describe without values, and platform session snapshots.

"I changed the credential but the old value is still used" — suspect your own caching before suspecting the credential layer. DSH plugin's credential seam requires re-resolution per operation; that per-operation read is the hot-reload mechanism, not a defect.

Credentials keep secrets out of configuration

Configuration stores references; providers own values.(source)

The credential seam in dsh-credentials keeps secrets out of configuration: settings sections and cordis.yml entries carry references (environment variable names), while values belong to providers such as dsh-credentials-local.

Consumers resolve a reference once per operation — an LLM adapter resolves once per model request, so a rotated credential affects the very next request without any restart.

One seam-wide rule binds every provider: an empty stored value is treated as absent everywhere.

Two key spaces answer two questions

References may fall back; records never do.(source)

CredentialRef answers "what is behind this environment variable name": it consults provider-managed storage first, then falls back to environment layers such as the process environment and .env files. An empty stored value counts as absent throughout this half — resolve skips it and describe reports unconfigured — so a blank can never masquerade as a configured secret.

CredentialKey answers "which credential does this plugin hold for this id." There is no layering here: authorization grants have no readable environment, so the record's existence is the entire fact. modifyRecord is the only write path, because a correct write depends on the current value — token refresh is a read, decide, replace sequence inside one lock.

Do not mix the two spaces: to configure an API key use CredentialRef; to store an OAuth grant use CredentialKey.

The record half has three more methods: readRecord(key) returns exactly what the owner wrote without interpreting the GrantRecord payload; describeRecord(key) reports only existence, discriminant fields, and writability; listRecords() enumerates each record's address and label without values. The reference explains why only records need enumeration: settings schemas tell the settings UI that references exist, while records have no such discovery path, so without listing you could neither see what a user authorized nor find orphans left by uninstalled plugins.

modifyRecord(key, mutate) exclusion holds across processes where storage supports it, which is the precondition for safe token refresh — otherwise two processes rotating one refresh token would let the earlier write be overwritten.

Resolution: re-resolve on every operation

The source layer tells you where a value came from, which helps debugging more than the value.(source)

A reference names one credential using a POSIX-style environment variable name. The brand prevents callers from confusing credential references with other strings passed between packages or processes, and construction validates shell identifier syntax.

resolve(ref) returns the value plus the source layer that supplied it (provider-defined; the local provider uses env, file, project-env, and user-env), or undefined while unconfigured.

Consumers re-resolve inside every operation and never cache across operations. That discipline produces hot reload: save a new value in the settings page and the next model request uses it. Conversely, if a plugin stores a resolve result in a long-lived variable, invalidation becomes your problem.

set(ref, value) accepts non-empty values only, and stored values take precedence over environment fallbacks; unset(ref) on a nonexistent reference is a no-op, and removal lets an environment layer take effect again. These semantics are consistent across providers, so do not write "read then check for empty string" workarounds.

describe: facts for the settings UI, no values

masked is a redacted preview, not the credential.(source)

describe(ref) answers the settings UI without ever exposing a value: whether the reference resolves now, which layer supplied it, and whether set would currently succeed. Optional masked carries a provider-generated redacted preview that never includes the full credential.

The local provider orders its managed file before the startup environment, so a saved value always becomes the effective writable layer; removal falls back to the startup environment or .env values again.

That explains two observed behaviors: source becoming the provider layer after a save is expected, and a value "coming back" after removal is a fallback layer taking effect, not a failed delete.

Committed changes only serve UI refresh

reference-updated is not for business consumers.(source)

credentials/reference-updated(ref) fires after a committed change in a provider-managed source — set, unset, or an external edit observed in storage. Changes to the process environment itself are unobservable and never emit.

Consumers do not need the event, since they re-resolve per operation; it serves the settings UI refreshing its "configured" badge.

That division means waiting for this event to trigger a reconnect is wrong; the correct move is to resolve again on the next operation.

CredentialsController carries the wiring duties outside the seam: batch fan-out limits, per-field view projection, reference syntax validation, and rejection mapping. Full secret values flow in one direction only, and no method here returns one.

Embedded platform credentials reuse a snapshot

A null userId never delays the caller.(source)

PlatformSession is the host-only snapshot getPlatformSession returns: origin names the configured platform issuing source, and token holds its stored account credentials.

userId copies the stable account id from the last successful getProfile; it is null before any successful read or when the profile carries no id. The snapshot reuses that id and issues no profile request of its own, so an unknown id only makes userId null rather than delaying the caller.

When a profile read first obtains a stable id or that id changes, only Host subscribers using watch(signal, true) are notified so identity consumers can re-read the snapshot. Consumers key persistent browser storage by origin and userId, falling back to ephemeral storage when it is null.

Two failure semantics: no snapshot is returned when the account is signed out or credentials change during the read, and a mismatched issuing source fails. Native consumers are responsible for invalidating documents when credentials change. The account remote API, AccountView, and AccountDetails all exclude this snapshot — it is a host-internal fact, not general browser data.

Verification: commit a change and re-resolve

Cover source-layer switching, empty-value rejection, and the UI event.(source)

  1. While unconfigured, resolve and assert undefined with describe().configured false.
  2. Call set(ref, 'sk-test') and assert resolve immediately returns the new value with a provider-layer source.
  3. Call set(ref, '') and assert rejection rather than storing an empty string.
  4. Call describe and assert masked exists but never contains the full value.
  5. Call unset(ref) then resolve again and assert a fallback layer (environment or .env) applies again, or undefined returns.
  6. Without restarting anything, verify the next request used the new value.

If step 3 stored an empty string, check whether you bypassed the seam and wrote storage directly — empty-value semantics are a seam-wide rule providers must honor.

For CredentialRef resolution precedence, see the credentials seam overview; for credentials in the settings panel, see settings panel configuration.

One line to close: references fall back while records do not, per-operation resolution is hot reload, empty means absent, describe gives masked previews only, reference-updated serves the UI, and PlatformSession reuses the id without delaying callers.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Does changing a DSH plugin credential need a restart?

No. DSH plugin has consumers re-resolve on every operation. DSH plugin forbids caching across operations, and that per-operation read is precisely the hot-reload mechanism.

Does an empty DSH plugin credential value take effect?

No. DSH plugin treats an empty stored value as absent everywhere. DSH plugin's resolve skips it and describe reports unconfigured, so clearing requires unset.

Do DSH plugin environment changes emit reference-updated?

No. DSH plugin states that changes to the process environment itself are unobservable. DSH plugin emits that event only for committed changes in provider-managed sources.

Does DSH plugin PlatformSession fetch profile data?

No. DSH plugin reuses the account id from the last successful read. DSH plugin leaves userId null when the id is unknown instead of delaying the caller with a profile request.

Related Terms

CredentialRef
CredentialRef is a branded credential reference named after a POSIX-style environment variable, validated against shell identifier syntax at construction.— packages/credentials/credentials/src/index.ts
CredentialKey
CredentialKey answers which credential a plugin holds for a given id; the existence of the record is the entire fact.— packages/credentials/credentials/src/index.ts
ResolvedCredential
ResolvedCredential is one resolution result with a non-empty secret value and a provider-defined source layer id.— packages/credentials/credentials/src/index.ts
PlatformSession
PlatformSession is the host-only snapshot getPlatformSession returns: issuing origin, account credentials, and a nullable stable userId.— packages/credentials/credentials/src/index.ts

Sources