From c206e382ef1f712ca6a7f0657b6bd8daefabe252 Mon Sep 17 00:00:00 2001 From: harry-harish <22562634+harry-harish@users.noreply.github.com> Date: Wed, 8 Jul 2026 20:10:31 +0530 Subject: [PATCH 1/2] docs(peek-cli): document peek connect + sessions search; refresh whats-new + THREATMODEL header MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - packages/peek-cli/README.md: add peek sessions search and peek connect (add/list/remove/start/stop/status/logs) to the Commands code block; add a "Connector daemon" subsection describing the supervised daemon architecture. - apps/peek-docs/src/pages/whats-new.astro: add sections 5-7 for search_sessions/verify_audit_log, peek connect daemon, and the Claude Code plugin (peekdev@peek) — all shipped but previously unlisted. - docs/peek/THREATMODEL.md: replace the stub header with an accurate "substantive" status noting the extension is CWS-live and residual gaps are accepted pre-1.0 scope. - .changeset/peek-cli-readme-connect-search.md: patch changeset for the README documentation update. Co-Authored-By: Claude Sonnet 4.6 Signed-off-by: harry-harish <22562634+harry-harish@users.noreply.github.com> --- .changeset/peek-cli-readme-connect-search.md | 5 ++ apps/peek-docs/src/pages/whats-new.astro | 55 ++++++++++++++++++++ docs/peek/THREATMODEL.md | 17 +++--- packages/peek-cli/README.md | 28 ++++++++++ 4 files changed, 96 insertions(+), 9 deletions(-) create mode 100644 .changeset/peek-cli-readme-connect-search.md diff --git a/.changeset/peek-cli-readme-connect-search.md b/.changeset/peek-cli-readme-connect-search.md new file mode 100644 index 00000000..7932b1c8 --- /dev/null +++ b/.changeset/peek-cli-readme-connect-search.md @@ -0,0 +1,5 @@ +--- +"@peekdev/cli": patch +--- + +docs(peek-cli): document the peek connect and peek sessions search commands in the README diff --git a/apps/peek-docs/src/pages/whats-new.astro b/apps/peek-docs/src/pages/whats-new.astro index e2fe37ab..1f1e259f 100644 --- a/apps/peek-docs/src/pages/whats-new.astro +++ b/apps/peek-docs/src/pages/whats-new.astro @@ -144,6 +144,61 @@ import Layout from '../layouts/Layout.astro'; See it: Reproduce a bug from a teammate’s peek session.

+

5. Find sessions and verify integrity from the CLI

+

+ Two CLI additions make the local store easier to triage and audit: +

+ + +

6. Delegated connectors — supervised background daemons

+

+ peek connect is a supervised connector daemon: register a + surface (currently Slack), run it once interactively to + capture tokens, then peek connect start spawns a detached + supervisor that keeps each connector alive and auto-restarts it on exit. + Per-connector logs stream to ~/.peek/connect/logs/; the + supervisor PID and each connector’s state are visible via + peek connect status. Connectors extend peek’s reach + beyond the browser — a Slack connector turns channel messages into + queryable local sessions the same way the extension turns browser activity + into sessions. +

+ +

7. Claude Code plugin

+

+ peek is now a one-line Claude Code plugin install: +

+ 
/plugin install peekdev@peek
+

+ This drops the peek MCP server and the Claude Code skill into place in a + single command — no peek init required for MCP + configuration. The plugin is hosted in the + public repo + and installable via the community catalog + (/plugin marketplace add Cubenest/rrweb-stack). +

+

The honest part

peek is local-first: peek uploads nothing — what your MCP diff --git a/docs/peek/THREATMODEL.md b/docs/peek/THREATMODEL.md index 6167f183..a2ee55db 100644 --- a/docs/peek/THREATMODEL.md +++ b/docs/peek/THREATMODEL.md @@ -1,8 +1,12 @@ -# peek — threat model (DRAFT) +# peek — threat model -**Status:** stub. To be filled in before public Chrome Web Store submission -(Phase 5 launch gate). Existence-tracking only — the gap is intentionally -visible. +**Status:** substantive — all eight attack surfaces enumerated, existing +mitigations documented, and outstanding items tracked with explicit scope +labels. The extension is live on the Chrome Web Store. Residual gaps +(content-script isolation hardening, native-host fuzz coverage, CWS +publisher 2FA recovery, CDP-debugger UX wording, `execute_action` schema +versioning) are accepted pre-1.0 scope and tracked below under +[Outstanding mitigations](#outstanding-mitigations). **Owner:** harry-harish. @@ -12,11 +16,6 @@ Cross-referenced from [`SECURITY.md`](../../SECURITY.md) and the project's pre-launch supply-chain hygiene controls (see `docs/SUSTAINABILITY.md` §"Pre-launch hygiene controls"). -When this stub is replaced, follow the format described in the OSS -Maintenance Field Manual §5.3 — one surface per row in each table, -explicit grade (`mitigated` / `partial` / `accepted` / `open`), and a -"why we live with it" column for any accepted risk. - ## Attack surfaces to cover 1. **Chrome MV3 service-worker compromise** — what happens if an attacker diff --git a/packages/peek-cli/README.md b/packages/peek-cli/README.md index b9f79be0..6256df55 100644 --- a/packages/peek-cli/README.md +++ b/packages/peek-cli/README.md @@ -46,6 +46,7 @@ Then you install the **Peek Chrome extension** — available on the [Chrome Web peek init # interactive install (see above) peek status # health check — extension connected? DB writable? peek sessions list [--origin ] [--limit ] [--json] # list recent sessions +peek sessions search [--q ] [--origin ] [--since ] [--until ] [--status ] [--errors ] [--limit ] [--json] # search sessions by metadata/facets peek sessions show # print one session as Markdown (metadata + errors) peek sessions export [--format ] [--out ] # export (default markdown); --format bundle writes a portable *.peekbundle peek sessions import [--keep-id] [--force] # import a *.peekbundle into the local store (local-first, masked-at-capture, no cloud) @@ -57,6 +58,13 @@ peek retention preview [overrides…] # dry-run: what the policy would pr peek retention apply [--yes] [--include-stale-active] [overrides…] # prune per the policy (asks to confirm) peek audit log [--since ] [--tool ] [--client ] [--json] # act-tool audit log peek audit verify [--json] # verify the audit log hash chain (exit 0 ok, 1 anomaly, 2 tampered) +peek connect add [--name ] [--command ] [--args=] # register a connector (surface: slack) +peek connect list # list configured connectors +peek connect remove # remove a connector from the registry +peek connect start # start the detached supervisor daemon +peek connect stop # stop the running supervisor daemon +peek connect status [name] # show supervisor and per-connector status +peek connect logs [name] [--follow] [--lines ] # print or tail connector logs peek --help # usage for any subcommand ``` @@ -93,6 +101,26 @@ The audit log (`~/.peek/audit.log`) is hash-chained: each JSONL entry carries a The audit log is **tamper-evident, not tamper-proof.** It detects accidental corruption, truncation, reordering, and edits, but does not stop a determined local attacker who recomputes the whole chain. There are no keys, no external anchor, and no egress. +### Connector daemon + +`peek connect` manages a supervised connector daemon — a long-running background process that spawns and monitors per-surface connector subprocesses (e.g. a Slack connector that streams workspace events into the local store). Connector registrations are stored in `~/.peek/connect/connectors.json`; the daemon runs detached and logs each connector's stdout/stderr to a per-connector file under `~/.peek/connect/logs/`. + +```sh +# First, register a connector for a surface (currently: slack). +# Run it interactively once to capture tokens and pair the connection, +# then start the daemon so it supervises and auto-restarts it. +peek connect add slack --name my-slack +peek connect start # spawns the detached supervisor + +# Ongoing management +peek connect status # show supervisor uptime + connector states +peek connect logs my-slack # last N lines of the connector's log +peek connect logs my-slack --follow # tail -f the log (Ctrl-C to stop) +peek connect stop # graceful SIGTERM to the supervisor +``` + +The `--args=` flag on `connect add` is repeatable — pass it multiple times to build the connector's argv. `--command` overrides the default binary for the surface (useful for a custom connector binary). + ## Querying from an AI agent After `peek init`, the `peek-mcp` server is available to your AI client as an MCP toolset. Sample queries: From 64fb3a209c0078af4701324083c2d1881bb3edc0 Mon Sep 17 00:00:00 2001 From: harry-harish <22562634+harry-harish@users.noreply.github.com> Date: Wed, 8 Jul 2026 20:19:37 +0530 Subject: [PATCH 2/2] docs(peek-cli): document peek audit bundle + verify --dir/--bundle flags CodeRabbit flagged the audit command list as out of sync: it showed only `log` and `verify` and omitted the shipped `peek audit bundle` subcommand. - Add `peek audit bundle [--dir ] [--out ]` to the Commands block. - Update `peek audit verify` to show its real flags (`--dir`, `--bundle`, `--json`) in both the Commands block and the Audit-log-integrity prose. - Add a parallel prose sentence describing `peek audit bundle` and how a recipient verifies a received *.peekaudit archive. Flags sourced verbatim from packages/peek-cli/src/commands/audit.ts USAGE and audit-bundle.ts. Docs-only; changeset unchanged (@peekdev/cli patch). Co-Authored-By: Claude Sonnet 4.6 Signed-off-by: harry-harish <22562634+harry-harish@users.noreply.github.com> --- packages/peek-cli/README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/packages/peek-cli/README.md b/packages/peek-cli/README.md index 6256df55..34ebf69e 100644 --- a/packages/peek-cli/README.md +++ b/packages/peek-cli/README.md @@ -57,7 +57,8 @@ peek retention show # print the configured policy peek retention preview [overrides…] # dry-run: what the policy would prune (non-destructive) peek retention apply [--yes] [--include-stale-active] [overrides…] # prune per the policy (asks to confirm) peek audit log [--since ] [--tool ] [--client ] [--json] # act-tool audit log -peek audit verify [--json] # verify the audit log hash chain (exit 0 ok, 1 anomaly, 2 tampered) +peek audit verify [--dir ] [--bundle ] [--json] # verify the audit log hash chain, or a received *.peekaudit archive (exit 0 ok, 1 anomaly, 2 tampered) +peek audit bundle [--dir ] [--out ] # package the audit log + head into a portable *.peekaudit evidence archive peek connect add [--name ] [--command ] [--args=] # register a connector (surface: slack) peek connect list # list configured connectors peek connect remove # remove a connector from the registry @@ -86,7 +87,7 @@ A policy can prune by age (`--max-age`), by total event-blob size (`--max-size`, The audit log (`~/.peek/audit.log`) is hash-chained: each JSONL entry carries a `seq` counter and a `prevHash` field (SHA-256 of the previous line), written under a file lock. A small sidecar (`audit.head.json`) records the tail hash so that tail truncation is also detectable. -`peek audit verify [--json]` recomputes the chain and reports: +`peek audit verify [--dir ] [--bundle ] [--json]` recomputes the chain and reports: | Status | Meaning | Exit code | |---|---|:---:| @@ -101,6 +102,8 @@ The audit log (`~/.peek/audit.log`) is hash-chained: each JSONL entry carries a The audit log is **tamper-evident, not tamper-proof.** It detects accidental corruption, truncation, reordering, and edits, but does not stop a determined local attacker who recomputes the whole chain. There are no keys, no external anchor, and no egress. +`peek audit bundle [--dir ] [--out ]` packages the audit log and its head sidecar into a portable `*.peekaudit` evidence archive (with a SHA-256 integrity manifest); a recipient verifies it independently with `peek audit verify --bundle `. + ### Connector daemon `peek connect` manages a supervised connector daemon — a long-running background process that spawns and monitors per-surface connector subprocesses (e.g. a Slack connector that streams workspace events into the local store). Connector registrations are stored in `~/.peek/connect/connectors.json`; the daemon runs detached and logs each connector's stdout/stderr to a per-connector file under `~/.peek/connect/logs/`.