# Security model

## Safe defaults

- Replay misses use `error`; they do not contact a live server.
- Passthrough requires an explicit mode and an original server argv.
- Redaction is enabled while recording and is repeated before UI display.
- Cassettes default to `.dsh-echo/`, which is ignored by Git.
- Fixture export runs a secret scan, refuses an existing destination, and
  requires the destination to remain below the chosen fixture root.
- Profile generation uses argv arrays and produces new overlay/recovery files.
- Browser APIs use configured IDs and normalized root-contained paths.

## What redaction does not prove

Redaction covers structured credential keys and known token shapes in JSON-RPC
frames, raw lines, command arguments, URLs, and UI responses. It cannot know
every application-specific secret or personal-data format. Its short hashes
exist only to correlate repeated placeholders and are not a security boundary,
especially for low-entropy values.

Treat every cassette as sensitive untrusted input. Scan and manually review an
export before committing or sharing it. Do not assume a passing scanner means
the file is public-safe.

## Side effects

`record`, `check`, `snapshot`, `verify`, and passthrough can execute or contact
the target the operator supplied. A tool call may send a message, charge money,
modify data, or delete data. Never aim those commands at production without
understanding the target. Replay without passthrough is the only offline
execution mode.

The DSH v0.1 HTTP adapter intentionally omits passthrough. stdio passthrough is
visible in configuration as both `--on-miss passthrough` and the original argv.

## Sensitive persistence

The Session annotation stores references and compact matching metadata, not a
second full copy of arguments/results. DSH itself may still persist its normal
tool event, so its Session storage must be protected according to the user's
own DSH deployment. The cassette remains the plugin's sensitive source of
truth and is never uploaded automatically.

Incomplete or interrupted JSONL is detected by the reader. Host unload closes
owned loopback listeners. For stdio, DSH owns the wrapper process and tears it
down with the configured MCP client.

## Threat checklist before sharing

1. Export with `dsh-echo export-fixture`, never by copying a raw session.
2. Search the exported file for organization names, emails, internal paths,
   hostnames, IDs, and application-specific credentials.
3. Confirm the header command and URL reveal no private infrastructure.
4. Review every raw entry and tool result.
5. Keep only synthetic data in public fixtures.

Security issues in the derivative should be reported through the repository
operator's private security channel once a hosting repository is configured.
Upstream-only engine issues should also be compared with the exact revision in
[UPSTREAM.md](../UPSTREAM.md) before disclosure.