Skip to content

Keep secrets from <Elicit> out of journals and verbose output #462

Description

@taras

Story

As an executable-document author, I want a credential collected by <Elicit>
to remain secret, so journals and verbose output cannot preserve a value the run
needed only in memory.

Example

A publishing workflow asks for a one-time code and uses it in a command.

The workflow succeeds, but the code does not appear in:

  • the <Elicit> result stored in the journal;
  • an eval-binding snapshot;
  • the command's recorded name or arguments;
  • --verbose output; or
  • ordinary rendered output.

An unmarked ordinary answer keeps today's record and replay behavior.

Current gap

An answer obtained at runtime currently reaches several records verbatim:

  • <Elicit> stores the answer as its result;
  • eval bindings may snapshot the value;
  • a command may include it in both its operation name and recorded arguments;
    and
  • --verbose prints the same records to standard error.

The existing secret scanner does not reliably recognize short one-time codes or
other values that look like ordinary data. The document also cannot inspect the
CLI's journal or verbose flags and refuse them.

Warnings telling an operator not to use --journal or --verbose are therefore
the only available protection today. A security guarantee must not depend on
the operator remembering that warning.

Secret marking

Before implementation, settle one author-visible, field-level way to mark an
elicited value as secret. Prefer a schema annotation beside the field it
describes over a separate journal policy that can drift from the input contract.

The marking must be available to every boundary that may record or display the
value. It cannot be lost when the value passes through an eval binding or into a
command request.

Unmarked values retain existing behavior. This feature does not redact all
elicitation results unconditionally.

Recording behavior

For a marked secret:

  • the journal may record that a secret elicitation completed, but not the secret
    value;
  • eval snapshots omit or redact the secret field without serializing it into a
    hidden alternate location;
  • command records preserve a useful non-secret operation identity without the
    disclosing argument text;
  • verbose output follows the same disclosure rule as the journal; and
  • in-memory execution may still pass the value to the operation that needs it.

Redacted placeholders must not contain a reversible encoding, stable hash useful
for guessing, or another derived value that discloses the secret.

Replay

Because the secret is not durable, replay cannot restore its value.

When execution reaches the marked elicitation again, XMD asks for a new secret.
It does not fail merely because the previous value was intentionally omitted,
and it does not treat the redacted journal entry as an answer.

Completed effects after the elicitation follow their ordinary replay contract.
A completed command is not repeated merely to obtain the secret again.

Security boundary

  • Secret marking supplements the existing secret scanner; it does not weaken or
    disable detection for unmarked values.
  • The contract covers XMD journals, diagnostic snapshots, recorded operation
    descriptions, and verbose output.
  • It does not claim to hide a secret from the external program that must receive
    it or from operating-system facilities outside XMD's control.
  • Successful rendered output remains unchanged except that no marked secret may
    appear there.

Acceptance

  • A marked <Elicit> answer completes an ordinary run.
  • The exact runtime-only secret is absent from the journal, verbose standard
    error, eval snapshots, command records, and rendered output.
  • A paired unmarked answer remains recorded, proving that redaction is
    intentional rather than unconditional.
  • Replay asks again when it reaches a marked secret whose value was not retained.
  • Completed effects are not repeated solely because an earlier secret was
    omitted.
  • Secret scanning remains enabled and unchanged for other values.
  • The npm bootstrap workflow can remove its warning against --journal and
    --verbose, or documents the separate reason that still requires it.
  • Architecture and executable-MDX specifications describe the same marking,
    recording, and replay behavior.

Evidence

Run one document with a runtime-only secret under ordinary, journal, verbose,
and replay scenarios. Search every produced output and record for the exact
value.

Pair it with an unmarked control. A negative control that removes the marking
must make the journal assertion fail.

Related work

Metadata

Metadata

Assignees

No one assigned

    Labels

    securitySecurity hardening

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions