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..34ebf69e 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) @@ -56,7 +57,15 @@ 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 +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 ``` @@ -78,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 | |---|---|:---:| @@ -93,6 +102,28 @@ 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/`. + +```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: