# Upstream audit

Audit date: 2026-08-27

## Baseline

- Repository: <https://github.com/ivermin1123/mcp-cassette>
- Commit: `9e48be26cbf1f7fca5edde142673a9b102a25e86`
- Package: `mcp-cassette@0.4.0`
- Runtime: Node.js 20 or newer, ESM, TypeScript
- License: Apache-2.0; no upstream `NOTICE` file was present

The clean upstream checkout passed `npm ci`, `npm run build`, `npx tsc -p tsconfig.json --noEmit`, and `npm test`. Vitest reported 30 passing files and 449 passing tests.

## Reusable modules

The public `src/index.ts` entry already exports the required engine boundaries:

| Capability | Module | Public API status |
| --- | --- | --- |
| Versioned JSONL and codec | `src/cassette.ts` | Exported |
| stdio recording | `src/record.ts` | Exported |
| Replay, fingerprinting, matching, miss diagnostics | `src/replay.ts` | Exported |
| Streamable HTTP recording | `src/proxy.ts` | Exported |
| Streamable HTTP/SSE replay | `src/http-replay.ts` | Exported |
| Secret redaction and scanning | `src/redact.ts` | Exported |
| Contract capture and schema drift | `src/snapshot.ts` | Exported |
| Value diff | `src/diff.ts` | Exported |

The CLI imports these APIs and only performs argument parsing, validation, and process exit handling. No core extraction or workspace migration is required for v0.1.

## Format and safety behavior

The current cassette format is version 2. Line one is a header and later lines are append-only frame, raw, or streamed-chunk entries. Readers retain version 1 compatibility and reject future versions. Headers record the recorder version, transport, start time, redaction flag, and protocol era.

Replay miss defaults to `error`. Passthrough requires an explicit mode and live server command, then appends interactions marked `origin: "live"`. Recording redacts by default. HTTP header values are not written. The redaction scanner covers credential-shaped headers, provider tokens, URL credentials, AWS credentials, and key-name patterns, but remains a best-effort control rather than a publication guarantee.

## Constraints retained for v0.1

- stdio recording owns a child process and process signal handlers; DSH must make the wrapper process part of the official MCP client's lifecycle instead of spawning an untracked duplicate.
- HTTP helpers return explicit async `close()` handles and are suitable for a Host effect disposer.
- Replay indexes are stateful because identical calls are consumed in recorded order. UI inspection must use a separate non-consuming summary.
- `verify` executes recorded calls against a real server and may cause side effects. DSH UI does not run it implicitly.
- Redacted cassettes may still contain missed secrets. Fixture export must scan and require human review.

## Decision

Keep the upstream single-package layout through v0.1 and add DSH integration under `src/dsh/`. Reuse the public core directly for inspection, HTTP lifecycle, redaction, and contract diff. Keep the generic CLI behavior compatible while adding DSH-specific subcommands and bundle exports.