ADR-0071: Secret input defaults and allowed values are dropped from the API, not masked
Context and Problem Statement
GET /api/v1/agents serves every agent's declared inputs to any console user holding any grant on that agent — there is no per-input authorization. The MCP tool schema for an exposed agent is served the same way to any caller holding a run grant. The agent schema lets an author declare an input secret: true and also give it a default (a fallback credential the run itself needs) and values. Before this decision both surfaces served those fields verbatim; the console's Run dialog only hid them at render time with !param.secret, a client-side check any HTTP caller skips. A run-time value outside a secret input's values was also rejected with a 400 that listed the whole allowed set.
Decision Drivers
- Any user holding any grant reads the agent summary, so the API — not the console — is the disclosure point (ADR-0047 §12 rule 7: secrets travel by reference, never by manifest).
- The run still needs the real default and the allow-list, so the agent definition and the run path (ADR-0052) keep them; only what is served narrows.
- Only
defaultandvaluescarry actual values of the credential.pattern,min/maxandminLength/maxLengthdescribe its shape, and a caller needs them to submit a valid value.
Considered Options
- (A) Drop
defaultandvaluesfrom what is served for a secret input, and keep the 400 for a value outsidevaluesgeneric. - (B) Mask them (serve a fixed placeholder such as
"•••") and let the console decide not to render it. - (C) Keep serving both and rely on the console's render-time
!param.secretgate.
Decision Outcome
Chosen option: "(A) drop, don't mask", because absence is the only representation the console already treats as "don't render" (default != null && !secret), and because the console is not the trust boundary — any HTTP caller with any grant reads the same endpoints.
Only default and values are dropped. pattern, min/max and minLength/maxLength describe a secret's shape, not the credential, so they stay served, and a secret value that fails pattern still gets a 400 naming the pattern. No error message repeats the secret value itself: a range denial states the bound without the "got …" part, and a load error for an invalid secret default or values entry omits the entry.
Redaction is keyed on secret: true and applied when the summary, the tool schema or the 400 is built, not stored anywhere. So an author who forgets the flag is not protected, but a flag added later protects the fields from the next agent reload on, with nothing to migrate.
Consequences
- Good: no client is trusted to keep the secret; the API never serves a flagged input's default or allowed values.
- Good: a late
secret: trueflag covers the fields retroactively. - Good: absence needs no new sentinel value and no console change — the dialog's existing "absent means don't render" contract just works.
- Bad: the protection still depends on the author setting the flag; an unflagged credential default is served like any other default.
- Bad: an author who declared
valueson a secret input to document the allowed set finds it gone from the summary and the tool schema; the agent definition remains the place that set is written down. The run path still enforces the allow-list, but a value outside it gets only "is not one of the allowed values". - Rejected (B): a mask is served data — the credential's presence still leaves the API, and the console must remember to not render it, which reintroduces the client gate as the boundary.
- Rejected (C): it trusts the client-side check any HTTP caller skips; the disclosure point is the API, so the guard must sit in the API.
More Information
Enforced at three points, each with a denial-path test:
AgentInfo.from— theGET /api/v1/agentssummary, for bothinputsand the legacyqueryParamsalias.McpToolFactory— the MCP tool schema'sdefaultandenum.ParamValidator— the generic 400 for a secret value outsidevalues; no other denial, at run time or load time, repeats a secret's value.
ADR-0052 is the run-path counterpart (redaction metadata captured with the run); ADR-0047 is the threat model this boundary answers to.