peach-browser / src / drafts / PCH-02-FIXES @ 4b29cedfa68e

INTEGRATION-CONTRACT.md

4.6 KB · raw

rendered · source

PCH-02-FIXES — Integration Contract

Source of truth for integrating these drafts. Where a patch file and this contract disagree, this contract wins.

Integration Contract

Files in src/drafts/PCH-02-FIXES/

Draft file Destination / role
README.md index — stays in drafts (or trash after integration)
INTEGRATION-CONTRACT.md this file — keep as reference (cited by tests)
PCH-02-001-vault-patch-sanitizers.patch.md edits → src/background/vault.ts:2375-2388
vault.update-entry-sanitize.test.ts → src/background/vault.update-entry-sanitize.test.ts
PCH-02-003-sas-trust-model-comment.patch.md edits → src/shared/chirp-handshake.ts:125-154
PCH-02-004-exact-pin-deps.patch.md edits → package.json:40-46; then bun install
WASM-PROVENANCE.md → repo root WASM-PROVENANCE.md (new file)
PCH-02-005-legacy-pbkdf2-doc.patch.md edits → src/shared/backup.ts:146 + src/popup/views/Import.tsx (3 hunks)
PCH-02-007-hibp-add-padding.patch.md edits → src/background/vault.ts:230
vault.hibp-padding.test.ts → src/background/vault.hibp-padding.test.ts
PCH-02-008-binaryreader-bounds.patch.md edits → src/crypto/peachPayload.ts:940-969 (+ export seam)
peachPayload.binaryreader-bounds.test.ts → src/crypto/peachPayload.binaryreader-bounds.test.ts
PCH-02-010-clipboard-hash-match.patch.md Option A (recommended): comment → src/background/clipboard.ts:18-19. Option B: clipboard.ts + offscreen.ts + manifest.json
clipboard.hash-match.test.ts → src/background/clipboard.hash-match.test.ts — Option B ONLY; do not integrate under Option A

Decisions required from the integrator (2)

  1. PCH-02-010 Option A vs B. Option B requires adding clipboardRead to manifest.json — a store-visible permission expansion ("Read data you copy and paste"). Recommendation: Option A now, Option B parked.
  2. PCH-02-004 papaparse hunk. The brief pins 5 packages; the report also cites papaparse. The patch includes it as an optional sixth line.

PCH-02-004 exact versions (read from bun.lock 2026-06-12 — pin, don't upgrade)

Package Pin
otpauth 9.5.0
pako 2.1.0
@zxing/library 0.23.0
bwip-js 4.11.1 (lockfile had drifted above the declared ^4.10.1)
pdf-lib 1.17.1
papaparse 5.5.3 (optional hunk)

After the edit run bun install (regenerates bun.lock; resolved tree is unchanged because every pin equals the installed version).

Estimated test count per finding

Finding New tests
PCH-02-001 8
PCH-02-003 0 — doc only (gateOnSAS already pinned by PCH-01-024 test)
PCH-02-004 0 — dependency metadata only
PCH-02-005 0 required (1 optional UI contract case sketched in the patch)
PCH-02-007 3
PCH-02-008 8
PCH-02-009 5
PCH-02-010 Option A: 0 — doc only / Option B: 4
Total 24 (Option A) / 28 (Option B)

Documentation-only findings (no tests needed)

PCH-02-003, PCH-02-005 (comment + notice), and PCH-02-010 under Option A.

Suggested integration order (one koh save each, tests green at every step)

  1. PCH-02-001 (the Low) + its tests
  2. PCH-02-007 and PCH-02-008 + tests (independent hardening)
  3. PCH-02-003 and PCH-02-005 (comments/UI)
  4. PCH-02-004 (package.json + bun install + WASM-PROVENANCE.md)
  5. PCH-02-010 (whichever option is chosen)
  6. Version bump + build all three targets (npm run build)

Gates after every save

Version bump recommendation

v4.0.0 → v4.0.1 (patch: hardening + docs, no feature surface) across package.json, manifest.json, manifest.firefox.json, then npm run build (all three targets, per project rule). If PCH-02-010 Option B is chosen, bump v4.0.0 → v4.1.0 instead — a new permission is not a patch-level change.

Out-of-scope observations recorded during drafting