lockpicks 0.4.0 → 0.6.0

package/LICENSE

@@ -0,0 +1,12 @@
+Copyright (c) 2026 Lockpick. All rights reserved.
+
+The Lockpick CLI and its deterministic Deep Local scanner are proprietary
+software. Their availability through a public package registry does not grant
+an open-source license. Use is subject to the applicable Lockpick service
+terms and entitlement. No right to redistribute Lockpick's proprietary code
+is granted by this notice.
+
+Third-party components retain their respective licenses. Their required
+copyright notices and license texts are included in THIRD-PARTY-NOTICES.txt
+or in the separately installed dependency packages. This proprietary notice
+does not restrict rights granted by those third-party licenses.

package/README.md

@@ -1,6 +1,6 @@
 # lockpicks
 
-Read your Lockpick results from the terminal, and give coding agents the same access over MCP: sites, scans, findings, repair briefs and recheck comparisons. If you allow it, the CLI and agents can also run a free quick check, add a site, start a Pulse check, check a DNS finding again and prepare a Deep scan that you approve in Lockpick. Pentests only start in the Lockpick web app, and the CLI never cancels or deletes anything.
+Read your Lockpick results from the terminal, and give coding agents the same access over MCP: sites, scans, findings, repair briefs and recheck comparisons. If you allow it, the CLI and agents can also run a free quick check, add a site, start a Pulse scan, check a DNS finding again and prepare a Deep scan that you approve in Lockpick. Master Key scans only start in the Lockpick web app, and the CLI never cancels or deletes anything.
 
 ## Sign in
 
@@ -8,7 +8,7 @@ Read your Lockpick results from the terminal, and give coding agents the same ac
 npx lockpicks login --host https://<your-lockpick>
 ```
 
-The browser opens a device page. Confirm the code, pick a workspace and approve. To let the key start Pulse checks, tick **Start Pulse checks** under **Extra permissions**; that box is your statement that you own the workspace's sites or may test them, and each Pulse started with the key is recorded under your name. Without it the key only reads. **Add sites and switch your free site** lets the key add sites (`lockpick sites add`). **Start Deep scans after you prove you own the site and approve each one** lets the key prepare Deep scans (`lockpick deep`); each still needs a verified ownership proof and your approval of that exact scan in Lockpick. `lockpick login --pulse --sites --deep` marks what the terminal asks for, but the browser never ticks anything for you and the key gets exactly what you tick. `lockpick whoami` shows what the key can do. The terminal receives a key bound to that workspace, stored in your OS keychain (or `~/.config/lockpick/config.json`, mode 0600, when no keychain is available). Each use extends the key; an idle key expires after the workspace's lifetime (30 days by default). Revoke it with `lockpick logout` or in the web app under **Workspace settings → CLI & agent access**.
+The browser opens a device page. Confirm the code, pick a workspace and approve. To let the key start Pulse scans, tick **Start Pulse scans on sites I own or may test** under **Also allow**; that box is your statement that you own the workspace's sites or may test them, and each Pulse started with the key is recorded under your name. Without it the key only reads. **Add and switch sites** lets the key add sites (`lockpick sites add`) and switch your free site. **Prepare Deep scans I approve** lets the key prepare Deep scans (`lockpick deep`); each still needs a verified ownership proof and your approval of that exact scan in Lockpick. `lockpick login --pulse --sites --deep` marks what the terminal asks for, but the browser never ticks anything for you and the key gets exactly what you tick. `lockpick whoami` shows what the key can do. The terminal receives a key bound to that workspace, stored in your OS keychain (or `~/.config/lockpick/config.json`, mode 0600, when no keychain is available). Each use extends the key; an idle key expires after the workspace's lifetime (30 days by default). Revoke it with `lockpick logout` or in the web app under **Workspace settings → CLI & agent access**.
 
 After an `npx` login, the CLI offers to install itself so you can type `lockpick` (or `lockpicks`) instead of `npx lockpicks`. To do it yourself:
 
@@ -26,24 +26,24 @@ Use HTTPS for a remote Lockpick host; a host without a scheme (`lockpick.app`) m
 | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `lockpick whoami`                      | The user, workspace and key this terminal uses                                                                                                                                                                      |
 | `lockpick doctor`                      | Checks Node.js, the selected host, connection, key, workspace and agent API without starting a scan                                                                                                                 |
-| `lockpick projects`                    | Projects with their latest Pulse and pentest                                                                                                                                                                        |
+| `lockpick projects`                    | Projects with their latest Pulse and box                                                                                                                                                                            |
 | `lockpick status [project]`            | One project's report, or an overview of all of them                                                                                                                                                                 |
-| `lockpick runs`                        | Pulse assessments and pentests, newest first                                                                                                                                                                        |
+| `lockpick runs`                        | Pulse assessments and boxs, newest first                                                                                                                                                                            |
 | `lockpick run <runId>`                 | One run: status, open findings, coverage and limits                                                                                                                                                                 |
 | `lockpick watch <runId>`               | Follows a run until it finishes                                                                                                                                                                                     |
 | `lockpick check <url>`                 | A free quick check of a website's homepage and public DNS; needs no site (key allowed to start Pulses)                                                                                                              |
-| `lockpick sites`                       | Sites with their latest Pulse and pentest                                                                                                                                                                           |
+| `lockpick sites`                       | Sites with their latest Pulse and box                                                                                                                                                                               |
 | `lockpick sites add <url>`             | Adds a site you own or may test (key allowed to add sites); adding does not scan it                                                                                                                                 |
 | `lockpick sites switch <site> --yes`   | Removes the site holding this month's free Pulse so another site can use it (key allowed to add sites and start Pulses); `--check <id>` also starts a Pulse on that quick check's site                              |
 | `lockpick pulse <project>`             | Starts a Pulse (a recheck of the latest one when possible) and waits for the result                                                                                                                                 |
-| `lockpick recheck <site>`              | A full recheck: a new Pulse that uses one free Pulse or 1 credit, then waits for it                                                                                                                                 |
+| `lockpick recheck <site>`              | A full recheck: a new Pulse that uses one Pulse scan from the allowance, then waits for it                                                                                                                          |
 | `lockpick recheck <runId> --dns <id>`  | Free: reads the public DNS records behind one DNS finding again; never contacts the site and never changes the grade                                                                                                |
 | `lockpick deps <site>`                 | Sends this folder's package names and exact versions (never code) to a site and lists the advisories that affect them (key allowed to add sites); `--dry-run` shows what would be sent, `--forget` removes the list |
 | `lockpick verify <site>`               | Verifies you own a site once: the site's value and where to publish it (`--method dns`, `file` or `meta`); `--wait` looks for it for about five minutes                                                             |
 | `lockpick deep verify <site>`          | The same proof, under `deep`                                                                                                                                                                                        |
 | `lockpick deep check <site> <id>`      | Looks once for the published proof; each check uses one of its attempts                                                                                                                                             |
 | `lockpick deep prepare <site> <id>`    | Prepares a Deep scan with a verified proof and opens its approval page; nothing starts until you approve                                                                                                            |
-| `lockpick deep start <operationId>`    | Starts the Deep scan you approved (one free Deep scan or 10 credits) and waits for it                                                                                                                               |
+| `lockpick deep start <operationId>`    | Starts the Deep scan you approved (one Deep scan from the allowance) and waits for it                                                                                                                               |
 | `lockpick findings <runId>`            | Findings that need attention (`--all` for informational ones)                                                                                                                                                       |
 | `lockpick finding <runId> <findingId>` | One finding with its evidence                                                                                                                                                                                       |
 | `lockpick brief <runId>`               | One brief that fixes everything needing attention (`--finding <id>` for one finding, `--agent <name>` to tailor it, `--out brief.md` to save it)                                                                    |
@@ -66,7 +66,7 @@ Text from scanned sites and saved briefs can carry terminal escape sequences. Th
 
 `pulse` and a full `recheck` started in a project folder with a lockfile ask once whether to send its package names and versions, and remember the answer for that folder (in the CLI's config folder, never in the project). `--lockfile` sends them for one run and `--no-lockfile` skips them; a script with no remembered answer never sends. Lockpick reads `package-lock.json`, `npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock`, `requirements.txt` (pinned lines only) and `poetry.lock` in the folder itself, not its subfolders.
 
-Each Pulse, and each full recheck, uses one of your account's runs, the same as starting it in the web app. A quick check and the DNS check again are free; quick checks are limited per account each hour and day.
+Each Pulse, and each full recheck, uses one of your account's Pulse scans, the same as starting it in the web app. A quick check and the DNS check again are free; quick checks are limited per account each hour and day.
 
 ## Coding agents (MCP)
 
@@ -86,6 +86,7 @@ Agents set up for CLI 0.2.0 keep working: `lockpick_list_projects`, `lockpick_pr
 | Variable              | Use                                                        |
 | --------------------- | ---------------------------------------------------------- |
 | `LOCKPICK_HOST`       | The Lockpick URL, instead of `--host` or your last login   |
+| `LOCKPICK_LANG`       | The language of the text the CLI prints (see below)        |
 | `LOCKPICK_KEY`        | A key to use without logging in (CI)                       |
 | `LOCKPICK_CONFIG_DIR` | Where the config file lives (default `~/.config/lockpick`) |
 | `LOCKPICK_KEYCHAIN=0` | Skip the OS keychain and use the config file               |
@@ -93,4 +94,63 @@ Agents set up for CLI 0.2.0 keep working: `lockpick_list_projects`, `lockpick_pr
 | `FORCE_COLOR=1`       | Colour even when output is not a terminal (CI logs)        |
 | `LOCKPICK_ACTION_REF` | The GitHub Action `ci init --action` refers to             |
 
+### Language
+
+The CLI prints in English, Japanese (`ja`), Korean (`ko`), French (`fr`), Spanish (`es`), German (`de`) or Brazilian Portuguese (`pt-BR`). Precedence: `--lang <code>` (or `--lang=<code>`, anywhere on the command line), then `LOCKPICK_LANG`, then `LC_ALL`, `LC_MESSAGES` and `LANG`, else English. The first one that is set decides; POSIX values such as `ja_JP.UTF-8` are read, `pt-PT` means `pt-BR`, and a set value that is not one of these languages (or `C`/`POSIX`) prints English.
+
+The language changes human text only. With `--json`, keys, `code` and `errorCode` fields, statuses, severities, ids, data values from Lockpick, and exit codes are identical in every language; only human-readable fields (such as `error`, and the text of checks) follow the chosen language. Command names, flags, and every value that came from a scan or a site are never translated, and the workflow YAML that `ci init` writes stays in English. The CLI sends the same language to Lockpick as `Accept-Language`, so messages from the server come back in it too.
+
 Requires Node.js 20.9 or later.
+
+## Check an assessment during development
+
+After deploying your repair and running an authorized scan, evaluate its exact run id:
+
+```bash
+lockpick ci check run_123 --fail-on high --max-age-hours 24 --min-coverage 80 --json
+lockpick report run_123 --out assessment.md
+lockpick report run_123 --json --out assessment.json
+```
+
+These commands read existing results and consume no scan allowance. `ci check` defaults to `--fail-on high`; freshness and coverage requirements are optional. It exits 3 for an unfinished/unsuccessful run or unmet freshness/coverage, 8 for findings at the severity threshold, and 0 when the selected policy passes. Missing or future completion timestamps fail a freshness requirement; unknown coverage fails any explicit coverage requirement, including zero. JSON includes the policy, reasons and public run data. This checks the recorded deployment, not your current local code or commit.
+
+`report` exports all public findings, including passing and unknown checks, with coverage limitations. Markdown labels finding content as untrusted data; JSON contains the public run and finding projections. Active runs must finish before export; failed and incomplete reports retain their status. `--out` refuses existing paths and requests mode 0600 on Unix; Windows uses the destination folder’s inherited ACLs. Without it, the report goes to stdout. A successful export says nothing about whether the assessment passed a policy.
+
+The same policy is available through local and hosted MCP as `lockpick_evaluate_scan`:
+
+```json
+{
+  "scanId": "run_123",
+  "failOn": "high",
+  "maxAgeHours": 24,
+  "minCoverage": 80,
+  "format": "json"
+}
+```
+
+It uses read permission, reads the existing scan once, and returns `passed`, `exitCode`, `policy`, `reasons` and the public run in the standard `{ data, error }` envelope. Policy failures are normal results (`passed: false`), while authorization and transport failures remain errors. The evaluator is shared with `ci check`; no scans start and no scan allowance is consumed. For report content, read `lockpick://scans/{scanId}/report` and follow any findings pagination. Saving that content is the calling client's responsibility.
+
+## Deep Local (candidate; rollout controlled)
+
+`lockpick deep local` runs deterministic checks on your computer after the API confirms project access and a Deep, Master Key or valid early-access entitlement. Local runs do not consume hosted scan credits. Request the separate permission with `lockpick login --local`.
+
+```sh
+lockpick deep local /absolute/repository --project <project-id> --json
+lockpick deep local /absolute/repository --project <project-id> --browser-artifacts .next/static --env-file .env.local --fail-on high
+```
+
+A project-bound CI key supplies its own project when `--project` is omitted. Personal keys require an explicit project.
+
+`lockpick whoami` and `/api/cli/v1/me` report every granted permission, including `local`. The canonical hosted agent identity reports hosted permissions only, keeping older clients compatible when a key also grants local scanning. This response filtering does not change the key's authority or the fresh local admission check.
+
+Launch a trusted installed CLI from outside an untrusted repository. Supply the physical absolute path of the selected root, with no symlink components; `pwd -P` in a trusted terminal at that location shows the physical path. The scanner does not resolve root symlinks automatically. Browser artifact directories and explicit environment files are relative to the selected root and may be repeated. The scanner never runs a build, target script or credential-validity request. Source and findings stay local; the admission request contains only versions and check IDs.
+
+Reports describe current tracked working-tree bytes, including unstaged changes. Explicit environment files can add untracked inputs. They do not prove production exposure or credential validity. JSON contains the same coverage and findings as terminal output; no source excerpts or secret values are returned. Missing, unsupported or incomplete checks stay explicit. Exit 3 means required coverage is incomplete; exit 8 means completed findings met an explicitly selected `--fail-on` threshold. Without that flag, findings alone do not change a completed run's exit code.
+
+Public-variable checks ignore comments, unrelated strings and arbitrary objects. Supported `process.env`/`import.meta.env` assignments and exported Next.js `env` configuration are parsed without executing configuration. Multiline dotenv text is kept inside its original value. Dynamic values, custom Vite configuration and unsupported syntax stay incomplete. Reports include sanitized explicit input paths, source inventory format/status, root framework context and migration order; exclusions are reported per check. An interrupted scan marks unknown inspection progress explicitly.
+
+This candidate implements current secrets, parsed dotenv and JS/TS public assignments for root-declared Next.js/Vite projects, explicitly supplied browser assets, and embedded source in `.map` files selected with `--source-maps`. Map findings identify the map container at line 1 and the exact embedded source line/UTF-16 column and index. Source names are sanitized; absolute paths and URLs receive an index label. Maps without embedded content are not applicable; malformed maps, unsupported external sections and missing map inputs are explicit incomplete results. Inline data maps remain unsupported. Add `supabase-client` or `actions-injection` to `--checks` for the implemented AST-based source checks. Supabase resolves exact imports and immutable literals or explicitly supplied env declarations; unresolved origin/browser context becomes a review item. The workflow rule covers direct attacker-controlled event interpolation in supported Bash/sh blocks and records unsupported parser/shell/flow context. Neither rule executes source. Docker ARG/ENV scanning is implemented via `docker-values`, with literal credentials separated from sensitive-name review items. Supply repeatable `--dockerfile` paths and matching `--build-context` paths (in the same order, `.` for the root) to add explicit-context `docker-files` checks. Applicable ignore rules and COPY stage locations are inspected without building an image; unsupported syntax and unresolved contexts stay incomplete. Context candidates cover sensitive filenames and credentials already detected by selected source checks. Untracked candidate contents stay unread unless supplied with `--env-file`; name-only cases are review items with unresolved context. Add `supabase-migrations` to inspect tracked `supabase/migrations/*.sql` in filename order, or repeat `--migration-file` to supply an explicit ordered set. Missing RLS and clearly permissive policies are source-level review items, with table/policy/role context; no SQL executes and no database exposure is claimed. Partial history, dynamic SQL and unsupported statements remain explicit. The embedded PostgreSQL parser is bounded and requires no download. Use `--history` to inspect at most 200 commits reachable from the pinned HEAD. Loose and packed SHA-1/SHA-256 objects are read locally without invoking Git or fetching anything. Historical credentials retain commit/path evidence and rotation guidance. Shallow history, missing/oversized objects, unsupported metadata and limits remain incomplete. Other branch tips, reflogs and unreachable objects are outside this scope. Platform/native packaging and staging verification are still in progress; public API admission remains disabled for the candidate. The candidate reader supports local APFS on macOS and ext-family/tmpfs on Linux, with x64/ARM64 native readers. Windows local scans and network/FUSE/overlay filesystems remain explicitly unsupported. Tracked-file inventory supports Git index v2/v3/v4; validated linked worktrees use their own index/HEAD and bounded common Git metadata. Split/sparse indexes and unsafe metadata pointers remain unsupported. Root and source symlinks are refused. This section is not an announcement that the scanner is live.
+
+Local MCP scanning is explicitly enabled with `lockpick mcp --local-root /absolute/repository`; repeat the flag for additional permitted roots. For generated client configuration, use `lockpick mcp config <client> --local-root /absolute/repository` (and `--apply` to install it). This cannot be combined with `--hosted`. The default MCP configuration does not expose `lockpick_scan_local`.
+
+The local tool takes a project ID, an absolute repository path within a configured root, check IDs and the same explicit relative inputs as the CLI. It uses the same admission/worker coordinator, rechecks authorization on every call, permits one local scan at a time and forwards cancellation to the worker. Results are not uploaded to Lockpick, but the calling MCP agent or model can see the redacted findings and paths. Do not enable local MCP if that disclosure is inappropriate for the repository.