DSH plugin credentials: CredentialRef and per-call resolve

The DSH plugin credential seam has one unbreakable rule: configuration carries references, never values. Settings sections and cordis.yml entries hold CredentialRef (an environment-variable name) while the actual secret belongs to a provider such as dsh-credentials-local; consumers re-resolve on every operation, so a rotated credential reaches the next request without a restart. The design also enforces a hard rule: an empty stored value is absent everywhere — resolve skips it and describe reports it unconfigured, so a blank can never masquerade as a configured secret. With those two ideas, reads, writes and descriptions all fall into place.

DSH plugin credential baseline: references in config, values in providers

Bottom line: a reference may live in configuration; the value belongs to the provider — that is what makes credentials safe to back up and share.

1. Configuration holds references: settings store environment-variable names, and cordis.yml entries do the same.
2. The provider owns values: the local provider reads from the process environment, its managed store and .env files.
3. Empty means absent: a blank stored value is never treated as configured.
4. Audit before committing: make sure no key-shaped string appears in configuration.
5. Verify: share the configuration with another machine — references remain, but the value must be configured separately.

DSH plugin's two key spaces: references and records

Bottom line: a reference answers "what is behind this environment-variable name"; a record answers "what does this plugin hold for this id."

1. References cover secrets: model API keys, third-party tokens.
2. Records cover grants: plugin-owned authorization such as OAuth.
3. References have no enumeration: configuration surfaces learn them from settings schemas; records must be enumerable so a UI can show grants and find orphans.
4. Do not mix them: resolving a record returns nothing.

DSH plugin per-operation resolve: why not to cache

Bottom line: re-resolving each operation is how hot rotation works; caching shuts rotation out.

1. Call shape:

const resolved = await ctx.credentials.resolve(ref)
if (!resolved) { /* unconfigured: report clearly, never request with an empty string */ }

2. LLM adapters are the model: resolve once per model request, so rotation applies to the next one.
3. Never cache across operations: the official contract forbids it; per-operation reads are the mechanism.
4. Unconfigured is undefined: branch on it instead of falling back to an empty string.
5. Verify: change the environment value without restarting and send the next request.

DSH plugin describe and CredentialInfo: why some references are read-only

Bottom line: describe returns facts and never values; writable: false means a read-only source shadows the reference.

interface CredentialInfo {
  configured: boolean
  source?: string
  writable: boolean
}

1. UI badges: configured state, supplying layer, and whether writing is possible.
2. The local read-only case: references supplied by the process environment report writable: false; a write would appear to succeed while resolution keeps returning the shadowing value, so the seam rejects it.
3. Render read-only early instead of letting users click and fail.
4. Change notification: credentials/reference-updated fires after set, unset or an observed external edit; process environment changes are unobservable and never emit.
5. Consumers do not need the event: per-operation resolution is enough; the event serves the UI.

DSH plugin writes: set/unset and modifyRecord

Bottom line: references use set/unset; records use only modifyRecord, the one safe way to refresh a token.

1. Reference writes:

await ctx.credentials.set(ref, value)   // empty values are rejected; use unset to remove
await ctx.credentials.unset(ref)        // removing an absent reference is a no-op

2. Shadowed writes are rejected: both set and unset refuse while a read-only source shadows the reference.
3. Record writes:

await ctx.credentials.modifyRecord(key, async (current) => next)  // undefined leaves it untouched

4. Why not read-then-write: two processes refreshing the same token would lose the first write; modifyRecord holds one lock for the whole read-decide-replace.
5. Authorization has its own entry: ctx.authorization registers credential-obtaining flows, one attempt per key, and a duplicate registration fails with DUPLICATE_FLOW.

DSH plugin credential troubleshooting

Bottom line: split failures into cannot read, cannot write and cannot see, then check shadowing or flow conflicts.

1. Cannot read — resolve returns undefined; check the variable name and provider layer.
2. Cannot write — check describe().writable (read-only shadowing).
3. Cannot see it in UI — references are not enumerable; ensure the settings schema declares it.
4. Rotation not applied — the plugin cached resolve results.
5. Token refresh lost writes — switch to modifyRecord.
6. Repair status, stated honestly: the two key spaces, empty-value rule, per-operation resolve and write refusal semantics follow the official User credentials page and package source notes; confirm signatures against the Cordis API block and your version.

Sources: User credentials, dsh-credentials source, Plugin config forms.