diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 0000000..eed1ae2 --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,32 @@ +# Security Policy + +## Supported versions + +The latest release gets fixes. The previous minor gets security-only patches for 90 days. There is +no update channel — PipDock does not update itself, so a fix reaches you when you download the new +build from [Releases](https://github.com/poli0981/pipdock/releases). + +## Reporting a vulnerability + +**Do not open a public issue.** Use either: + +- [GitHub Security Advisories](https://github.com/poli0981/pipdock/security/advisories/new) — preferred +- `code@poli0981.dev` + +Target acknowledgment is 7 days. Coordinated disclosure is preferred; tell us if you have a +disclosure deadline and we will work to it. + +Useful in a report: the PipDock version (it is on the **About** tab), the Windows version, the +engine (pip or uv) and its version, and the smallest sequence of steps that reproduces the issue. + +## What is in scope + +PipDock runs subprocesses against Python interpreters you point it at, so the interesting surface is +where untrusted input reaches a command line, a file path, or a URL handed to your browser. +[`docs/SECURITY.md`](../docs/SECURITY.md) is the full threat model — §2 (argv arrays, never a shell), +§3 (PEP 668), §4 (network and the opener allowlist) and §7 (supply chain) are the sections most +reports land in. + +Out of scope: vulnerabilities in the packages PipDock installs on your behalf — report those to the +package's own maintainers — and in pip, uv, deptry, vulture or ruff, which PipDock invokes but does +not distribute. diff --git a/CLAUDE.md b/CLAUDE.md index 6c33621..b8a75dd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -54,7 +54,9 @@ failed package never aborts a batch (skip-and-continue, then a `"13 successful, - Frontend lives in `ui/`, but `package.json` sits at the **repo root** so the ops-repo `reusable-web-react.yml` (which has no `working-directory` input) works unmodified; Vite is configured with `root: './ui'` -- Rust ↔ TS types are generated with `specta`/`tauri-specta` — never hand-mirror a type +- Rust ↔ TS types are generated by `cargo run -p xtask -- bindings` over `schemars` — never + hand-mirror a type. (ARCHITECTURE §9 originally said `specta`/`tauri-specta`; `bindings.rs` records + why it is not, and drift is a `cargo test` failure rather than a compile error) - No component calls `invoke` directly; everything goes through the typed wrappers in `ui/src/ipc/` ## CI reality diff --git a/README.md b/README.md index b0ab92f..c942839 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ **A friendly dock for your Python environments.** Inspect, install, update, and clean up Python packages in bulk — through a keyboard-first GUI or a scriptable CLI — without ever hand-typing another `pip install` incantation or guessing why an upgrade broke your project. -> Repo: `poli0981/pipdock` · License: **GPL-3.0** · Platform: **Windows 10/11 (v1)** · Status: **pre-release** — every v1 feature is built; the release pipeline and the manual charter are what remain +> Repo: `poli0981/pipdock` · License: **GPL-3.0-only** · Platform: **Windows 10/11** · Contact: [contact@poli0981.dev](mailto:contact@poli0981.dev) · [other channels](https://poli0981.dev/links/) --- @@ -95,7 +95,7 @@ pipdock snapshot rollback latest ## License -GPL-3.0. See [LICENSE](LICENSE) (add the standard GPL-3.0 text at repo creation). The legal documents in [legal/](legal/) must be committed publicly so the in-app legal gate can link to them on GitHub. +Copyright © 2026 Kokone (poli0981). PipDock is free software under **GPL-3.0-only** — see [LICENSE](LICENSE). The legal documents in [legal/](legal/) are committed publicly so the in-app legal gate and the About tab can link to them on GitHub. PipDock is an independent project. It is not affiliated with or endorsed by the Python Software Foundation (Python, pip, PyPI) or Astral (uv, ruff). diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index efbd7ee..5167c52 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -176,7 +176,7 @@ Uninstalls are always sequential (cheap) with the reverse-dep guard evaluated on ## 9. Frontend architecture -Zustand stores: `useEnvStore`, `usePlanStore`, `useIndexStore`, `useSettingsStore`, `useHealthStore`. All engine data enters via typed IPC wrappers (`ui/src/ipc/*.ts`) mirroring the Rust types (generated with `specta`/`tauri-specta` to prevent drift). No component calls `invoke` directly. i18next with `en`/`vi` JSON catalogs (see I18N.md). Styling via Tailwind 4 tokens defined in UI-SPEC. +Zustand stores: `useEnvStore`, `usePlanStore`, `useIndexStore`, `useSettingsStore`, `useHealthStore`. All engine data enters via typed IPC wrappers (`ui/src/ipc/*.ts`) mirroring the Rust types. **This section originally specified `specta`/`tauri-specta` and that is not what shipped:** `ui/src/ipc/generated.ts` comes from a first-party `xtask` over `schemars`, which makes drift a *test* failure rather than a compile error. `crates/pipdock-core/src/bindings.rs` records why — specta 2 is still `2.0.0-rc`, and a second derive stack over ~40 types was not worth it — and names the condition for revisiting. No component calls `invoke` directly. i18next with `en`/`vi` JSON catalogs (see I18N.md). Styling via Tailwind 4 tokens defined in UI-SPEC. ## 10. Version manifest (verified 2026-07; re-verify at implementation) diff --git a/docs/PRD.md b/docs/PRD.md index 5f3d2e4..42d75bb 100644 --- a/docs/PRD.md +++ b/docs/PRD.md @@ -22,7 +22,7 @@ PipDock's thesis: **don't reimplement the resolver — explain it.** Wrap pip/uv - G4 — Core happy paths complete in **≤ 5 clicks** (see UI-SPEC click budgets). - G5 — GUI and CLI share **one Rust core**; behavior never diverges. - G6 — PipDock **never modifies its own runtime** (standalone binary; the managed environments are external). -- G7 — Zero telemetry; network traffic limited to PyPI + GitHub Releases. +- G7 — Zero telemetry; **PyPI is the only host PipDock connects to.** It does not update itself, so it never calls home; GitHub, the ruff docs and the author's contact page are only ever handed to the browser as a link the user clicked (SECURITY §4/§5). ## 3. Personas diff --git a/docs/SECURITY.md b/docs/SECURITY.md index 2788910..2fde5e0 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -30,7 +30,9 @@ Environments carrying an `EXTERNALLY-MANAGED` marker are **blocked by default** `pypi.org` is the **only** host PipDock itself connects to. It does not update itself (§5), so it has no reason to reach `github.com` — the legal gate and the bug-report deep link hand a URL to the user's browser rather than fetching anything. The webview cannot reach either: `connect-src` in `tauri.conf.json` allows only `'self'` and the IPC origin, so all network access goes through Rust. -**Two hosts may be handed to the browser, and the allowlist is the record of why.** `capabilities/external-links.json` scopes `opener:allow-open-url` to `https://github.com/*` and, since Phase 3 · P4, `https://docs.astral.sh/*` — every ruff finding carries its own rule page and CODE-HEALTH-SPEC §6 as amended requires using ruff's `url` rather than constructing one. Neither is a connection PipDock makes; both are URLs it asks the OS to open. The widening is recorded here rather than only in `capabilities/` because an allowlist entry is a change to this document's subject matter, not a config detail — and because the failure mode of *not* widening it is silent: the promise rejects, nothing opens, and nothing anywhere says so. +**Three hosts may be handed to the browser, and the allowlist is the record of why.** `capabilities/external-links.json` scopes `opener:allow-open-url` to `https://github.com/*`; to `https://docs.astral.sh/*` since Phase 3 · P4 — every ruff finding carries its own rule page and CODE-HEALTH-SPEC §6 as amended requires using ruff's `url` rather than constructing one; and to `https://poli0981.dev/*` since Phase 4, for the one page the About tab links to that lists every other way to reach the author. None is a connection PipDock makes; all three are URLs it asks the OS to open. The widening is recorded here rather than only in `capabilities/` because an allowlist entry is a change to this document's subject matter, not a config detail — and because the failure mode of *not* widening it is silent: the promise rejects, nothing opens, and nothing anywhere says so. + +**What the scope actually defends is narrower than it looks.** Most call sites pass module constants no injected string can reach. Two pass data: `PdErrorRow` hands over a URL built in Rust, and `PdHealthReport` hands over `finding.url` — which comes out of **ruff's own JSON** over the user's source tree, and is the only URL in the application derived from a third-party tool's output. `https://docs.astral.sh/*` is precisely what stops that being anything else. That is also why the contact addresses in About are copied to the clipboard rather than opened: a `mailto:` entry would widen the allowlist by a whole URL *scheme*, and re-open a target class for that one call site, to save a paste. No telemetry, no crash reporting endpoints, no analytics. TLS failures surface as PD-NET-002 and the app **never** offers to disable verification. @@ -54,7 +56,7 @@ pip-audit runs **from the tools venv** in freeze-file mode: snapshot-freeze the - The `cargo audit` gate is on **vulnerabilities** and is never relaxed. `.cargo/audit.toml` ignores a fixed list of *informational* advisories — unmaintained/unsound — on transitive crates PipDock cannot influence, chiefly Tauri's archived GTK3 bindings, which a Windows-only build never compiles. They are listed individually with justification so a **new** advisory still fails CI. Adding macOS/Linux builds (P2-1) is the point at which that block must be re-examined rather than extended. - `Cargo.lock` and `package-lock.json` committed; builds are `--locked`. - CodeQL enabled via the ops-repo caller with the established permissions block, scoped to **`javascript-typescript` only** — CodeQL has no Rust analyzer. Rust's static-analysis coverage is clippy `-D warnings` plus `cargo audit`, both blocking in `ci-rust.yml`. -- Third-party licenses tracked in `legal/THIRD-PARTY-NOTICES.md`; `cargo about`/`license-checker` regenerate the inventory at release. +- Third-party licenses tracked in `legal/THIRD-PARTY-NOTICES.md`, which names the **direct** dependencies the manifests declare and is reconciled against them by hand at each release. It is not generated: an earlier revision of both documents claimed `cargo about`/`license-checker` produced it into a `licenses/` directory, and no such config, directory or release step has ever existed. The complete resolved graph is `Cargo.lock` and `package-lock.json`, both committed. Generating the inventory is tracked as a Post-1.0 item; until it lands, the claim here matches what is done. ## 8. Data & privacy engineering @@ -64,8 +66,10 @@ All state PipDock writes is local under `%LOCALAPPDATA%\PipDock\data\`. **One exception, and it is the only one.** `ruff check --fix` (CODE-HEALTH-SPEC §5, Phase 3 · P5) rewrites files in a project folder the user chose. It is PipDock's sole write outside site-packages and `%LOCALAPPDATA%`, it happens only behind an explicit confirm carrying a `FixConsent` the executing call demands, and it is refused entirely — before the first byte — if any target cannot be written. No snapshot is taken, because no snapshot in this application describes a source tree; the safety net is the user's own version control, which the confirm names and `git status` is consulted about twice. §1's threat model does not otherwise contemplate PipDock writing to user source, so this is the paragraph that says it does. -Logs may contain package names and paths — the bug-report flow shows the user exactly what will be prefilled and requires manual submission (ERROR-CATALOG §4). No identifiers are generated or stored beyond the random consent record. Deleting the app data folder is a complete reset (documented in Settings → Legal & About). +Logs may contain package names and paths — the bug-report flow shows the user exactly what will be prefilled and requires manual submission (ERROR-CATALOG §4). No identifiers are generated or stored beyond the random consent record. Deleting `data\` is a complete reset — and deleting the *parent* uninstalls the program, which is why the distinction is spelled out wherever the advice appears: `legal/PRIVACY-POLICY.md` §2 and the **About** tab. The Privacy Policy carried the pre-move wording for two weeks after the move; that is the failure this paragraph exists to prevent recurring. ## 9. Vulnerability reporting -`SECURITY.md` at repo root (this file doubles as it) will carry a private reporting channel via GitHub Security Advisories on `poli0981/pipdock`; target acknowledgment ≤ 7 days. Coordinated disclosure preferred; in-range CVEs in shipped dependencies trigger a patch release via the standard pipeline. +Report privately through **GitHub Security Advisories** on `poli0981/pipdock`, or by email to `code@poli0981.dev`; target acknowledgment ≤ 7 days. Coordinated disclosure preferred; in-range CVEs in shipped dependencies trigger a patch release via the standard pipeline. + +`.github/SECURITY.md` is the short pointer GitHub's *Security policy* tab renders, and it points here. This file is the policy; that one exists so the tab is not empty. diff --git a/docs/TESTING.md b/docs/TESTING.md index 920c027..0e99c6b 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -37,7 +37,7 @@ Fixture packages are tiny pinned PyPI wheels (documented list in `tests/integrat ### L3 — Frontend (Vitest + Testing Library) -Component tests for `PdConflictRow` (3-way state), `PdPreviewDiff` grouping, `PdSummarySheet` counts, dimming/badging rules on `PdPackageTable`, and the design-token contrast test (all text/surface pairs ≥ WCAG AA computed at build). IPC mocked at the typed wrapper layer with recorded core payloads — the same JSON as L1 fixtures, guaranteeing UI and core agree on shapes (types generated via tauri-specta make drift a compile error). +Component tests for `PdConflictRow` (3-way state), `PdPreviewDiff` grouping, `PdSummarySheet` counts, dimming/badging rules on `PdPackageTable`, and the design-token contrast test (all text/surface pairs ≥ WCAG AA computed at build). IPC mocked at the typed wrapper layer with recorded core payloads — the same JSON as L1 fixtures, guaranteeing UI and core agree on shapes. Types are generated by `cargo run -p xtask -- bindings` over `schemars`, not by tauri-specta as this line once said, so **drift is a test failure rather than a compile error** — which means it fires at `cargo test`, locally as well as in CI. See `crates/pipdock-core/src/bindings.rs`. ### L4 — CLI (assert_cmd + insta)