@proofofwork-agency/toolpin 0.2.3

package/CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing
+
+Thanks for improving ToolPin. This project is intentionally conservative:
+security-sensitive commands should fail closed, write the minimum config needed,
+and avoid overstating what ToolPin verifies.
+
+## Contributor License Agreement
+
+Before your first pull request can be merged, please sign the
+[Individual Contributor License Agreement](CLA.md). You only sign once, and it
+covers all your past and future contributions.
+
+The CLA is based on the widely-used Apache Individual CLA. It lets you keep your
+copyright while granting the maintainers the administrative rights needed to
+maintain the project and — if a hosted/commercial offering is ever shipped —
+relicense the project as a whole without fragmenting copyright. If you do not
+agree to it, you are still free to fork ToolPin under the Apache License 2.0.
+
+To sign, open a pull request adding one line to
+[`.cla-signatures/CLA_SIGNATORIES.md`](.cla-signatures/CLA_SIGNATORIES.md):
+
+```
+- Jane Doe <jane@example.com>
+```
+
+Use your real name and the primary email address used in your Git commits.
+
+## Development Setup
+
+Requirements:
+
+- Node.js 22 or newer.
+- npm 10.9.2 or compatible npm 10.
+
+```bash
+npm ci
+npm test
+```
+
+Useful commands:
+
+```bash
+npm run build
+node dist/cli.js help
+node dist/cli.js search github --limit 3 --live
+node dist/cli.js ci --file mcp-lock.json --live
+```
+
+Do not commit `node_modules/`, `dist/`, local cache files under `.toolpin/`, or
+private signing keys. Commit `mcp-lock.json` when the lockfile is the intended
+review artifact.
+
+## Project Conventions
+
+- TypeScript ESM, built with `tsc`.
+- Tests use Node's built-in `node:test`.
+- Keep CLI output stable enough for humans and tests; put machine-readable
+  behavior behind `--json`.
+- Prefer exact, explicit error messages for security failures.
+- Treat registry metadata and MCP tool descriptions as untrusted input.
+- Keep install, CI, and policy checks fail-closed. A missing integrity field,
+  failed signature, rejected policy, or lock drift should stop the operation.
+
+## Pull Requests
+
+Before opening a PR:
+
+1. Run `npm test`.
+2. Update README or docs when command behavior, install paths, lockfile
+   semantics, policy behavior, or security claims change.
+3. Add or update tests for security-sensitive behavior.
+4. Call out any intentional compatibility break in the PR description.
+
+Security-sensitive PRs should state:
+
+- Which boundary changed.
+- How the failure mode is handled.
+- Whether `toolpin ci`, `toolpin install`, TUI installs, or generated client
+  config are affected.
+
+## Curated Registry Contributions
+
+Curated registry PRs should edit JSON directly in both `registry/v0/servers`
+and `website/static/registry/v0/servers`; the files must stay identical. Each
+entry needs install metadata, `_meta["dev.toolpin/curation"]`, and
+`_meta["dev.toolpin/clientSupport"]`.
+
+Use client support statuses precisely:
+
+- `toolpin-installable`: ToolPin can generate the client MCP config directly.
+- `external-setup`: the client is supported through documented setup outside
+  ToolPin, such as plugins, daemons, project initialization, or instruction-file
+  writes.
+- `unsupported`: ToolPin must not offer that client as an install target.
+
+Run `npm run registry:check` before opening the PR. It validates malformed JSON,
+mirror sync, curation metadata, client support metadata, and enough package or
+remote config for direct ToolPin installs.
+
+## Documentation Standard
+
+Be precise about guarantees:
+
+- "Verifies" means ToolPin checked exactly what the code checks.
+- Presence checks are not byte-level verification.
+- Advisory scans are not prompt-injection detection.
+- `toolpin ci --expect-digest` is only meaningful when the expected digest
+  comes from a trusted source outside the PR being checked.
+- Detached signatures are only as trustworthy as the private key and public
+  trust root handling.
+
+## Coordinating With Agents
+
+This repository may have multiple agents working in parallel. Read
+`AGENTS.md`, stay inside your assigned scope, and never revert unrelated dirty
+work. If another agent has modified the same file, adapt to the current file
+contents and keep your diff narrow.

package/LICENSE

@@ -0,0 +1,183 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work (an example is provided in the Appendix
+below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner. For the purposes of this definition,
+"submitted" means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems, and
+issue tracking systems that are managed by, or on behalf of, the Licensor for
+the purpose of discussing and improving the Work, but excluding communication
+that is conspicuously marked or otherwise designated in writing by the copyright
+owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License,
+each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable (except as stated in this section) patent
+license to make, have made, use, offer to sell, sell, import, and otherwise
+transfer the Work, where such license applies only to those patent claims
+licensable by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s) with the Work
+to which such Contribution(s) was submitted. If You institute patent litigation
+against any entity (including a cross-claim or counterclaim in a lawsuit)
+alleging that the Work or a Contribution incorporated within the Work
+constitutes direct or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate as of the date
+such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any part
+of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents of
+the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may have
+executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties or
+conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any character
+arising as a result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill, work stoppage,
+computer failure or malfunction, or any and all other commercial damages or
+losses), even if such Contributor has been advised of the possibility of such
+damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree to
+indemnify, defend, and hold each Contributor harmless for any liability incurred
+by, or claims asserted against, such Contributor by reason of your accepting any
+such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "[]" replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same "printed page" as the copyright notice for easier identification
+within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License. You may obtain a copy of the
+License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -0,0 +1,323 @@
+# ToolPin
+
+[![CI](https://github.com/proofofwork-agency/toolpin/actions/workflows/ci.yml/badge.svg)](https://github.com/proofofwork-agency/toolpin/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+[![npm publish pending](https://img.shields.io/badge/npm-publish%20pending-orange)](https://www.npmjs.com/package/@proofofwork-agency/toolpin)
+[![Status: pre-1.0 beta](https://img.shields.io/badge/status-pre--1.0%20beta-yellow)](https://github.com/proofofwork-agency/toolpin/releases)
+
+ToolPin is a review gate for MCP server installs. It helps teams inspect what
+an MCP server will run, generate client config, commit an enforcing
+`mcp-lock.json`, and fail CI when the reviewed install drifts.
+
+Use `toolpin` for explicit commands or the shorter `tpn` alias for daily work.
+
+Public documentation: <https://proofofwork-agency.github.io/toolpin/>
+
+ToolPin is pre-1.0 beta software, Apache-2.0 licensed, and requires Node.js 22
+or newer.
+
+![Animated terminal demo showing ToolPin search, plan, install, audit, and CI drift-check commands.](docs/assets/readme/terminal-demo.svg)
+
+## Contents
+
+- [Highlights](#highlights)
+- [Screenshots](#screenshots)
+- [Why ToolPin](#why-toolpin)
+- [Getting Started](#getting-started)
+- [Usage](#usage)
+- [GitHub Actions](#github-actions)
+- [Safety Model](#safety-model)
+- [What Exists Now](#what-exists-now)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+- [Resources](#resources)
+
+## Highlights
+
+- **Review before install:** inspect registry metadata, selected target, trust
+  score, evidence tier, required secrets, and generated config before writing.
+- **One lockfile across clients:** write `mcp-lock.json` entries for Claude,
+  Cursor, VS Code, Codex, OpenCode, Continue, Gemini CLI, and more.
+- **CI drift checks:** reject changes in registry metadata, selected target,
+  config output, capability manifest, policy, signature, or evidence state.
+- **Registry-aware discovery:** ingest Official MCP Registry, Docker MCP
+  Catalog, the ToolPin curated registry, and configured custom registries.
+- **Local policy gate:** enforce minimum trust tier/score, source and client
+  allow/deny rules, remote endpoint rules, required-secret rules, and pinning
+  requirements.
+- **Terminal UI:** browse, inspect, install, update, adopt, remove, and test MCP
+  servers from an Ink-based TUI.
+
+## Screenshots
+
+ToolPin gives MCP installs the same review loop teams already expect for code:
+inspect the server, verify the evidence, preview the exact client config, then
+write a lockfile that CI can enforce.
+
+![ToolPin TUI browse overview with ContextRelay selected, verified evidence, trust scores, and install actions.](docs/assets/readme/tui-browse-overview.jpg)
+
+The TUI is built for repeated operations: source-aware browsing, registry/cache
+state, trust scoring, version selection, installed inventory, config preview,
+and one-key install/adopt/update/delete flows.
+
+| Config preview | Installed inventory |
+|---|---|
+| ![ToolPin TUI config preview showing the Claude project MCP JSON that will be written for a streamable HTTP server.](docs/assets/readme/tui-config-preview.jpg) | ![ToolPin TUI installed inventory showing locked and unlocked Codex MCP servers.](docs/assets/readme/tui-installed-inventory.jpg) |
+
+![ToolPin TUI help screen showing keyboard shortcuts, scoring explanations, locking behavior, sources, and installed actions.](docs/assets/readme/tui-help.jpg)
+
+## Why ToolPin
+
+Adding an MCP server is not like installing an editor theme. It can give an
+agent new tools, local process access, network access, and credentials. Today
+that decision is often a copied JSON snippet with no reviewed artifact and no
+CI check that says "this is still the server and config we approved."
+
+ToolPin turns that into a normal engineering control:
+
+1. Inspect the server and install plan.
+2. Generate the right config for the MCP client.
+3. Commit `mcp-lock.json` as the reviewed record.
+4. Run `toolpin ci` so drift is caught before it reaches users.
+
+ToolPin is not a hosted gateway, runtime sandbox, secret vault, or broad MCP
+marketplace. It sits between registries and clients as a local, repo-owned
+reproducibility layer.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 22 or newer.
+- npm.
+- Git.
+- One supported MCP client, such as Claude, Cursor, VS Code, Codex, OpenCode,
+  Continue, Gemini CLI, Windsurf, Cline, Roo Code, Zed, or a generic sidecar.
+
+### Install From npm
+
+```bash
+npm install -g @proofofwork-agency/toolpin
+toolpin --version
+tpn -v
+tpn upgrade --dry-run
+```
+
+`toolpin` and `tpn` are aliases for the same CLI. `toolpin upgrade` and
+`tpn upgrade` update the globally installed package; pass `--dry-run` to preview
+the package-manager command.
+
+### Develop From Source
+
+Use the source checkout when changing ToolPin itself:
+
+```bash
+git clone https://github.com/proofofwork-agency/toolpin.git
+cd toolpin
+npm ci
+npm test
+```
+
+Build the CLI:
+
+```bash
+npm run dev -- --help
+```
+
+## Usage
+
+### Search Registries
+
+```bash
+toolpin ingest --source all --limit 500 --pages 25
+toolpin search github --source all --limit 5
+```
+
+### Review an Install Plan
+
+```bash
+toolpin plan io.github.github/github-mcp-server \
+  --client claude \
+  --scope project \
+  --live
+```
+
+### Install and Lock
+
+```bash
+toolpin install io.github.github/github-mcp-server \
+  --client claude \
+  --scope project \
+  --live \
+  --verify \
+  --update-lock
+```
+
+The install writes client config and `mcp-lock.json`. Commit the lockfile so
+teammates and CI can reject drift.
+
+### Check Drift
+
+```bash
+toolpin doctor --scope project
+toolpin ci --file mcp-lock.json --live --verify
+```
+
+### Use the TUI
+
+```bash
+toolpin tui
+tpn tui
+npm run tui
+```
+
+Useful keys:
+
+| Key | Action |
+|---|---|
+| `/` | Search |
+| `tab` or `1-6` | Switch panels |
+| `enter` | Open selected install plan |
+| `i` | Install wizard |
+| `r` or `: ingest` | Persistently refresh registry cache |
+| `l` | Toggle live/cache view for the session |
+| `m` or `+` | Show more Browse results |
+| `a` | Cycle Browse sort: source-first, alpha A-Z, alpha Z-A, source-last, relevance |
+| `g` | Cycle the exact source filter (`all`, then enabled sources such as `toolpin`, `official`, `docker`) |
+| `S` | Show sources |
+| `I` | Show installed inventory |
+| `q` | Quit |
+
+See the hosted [CLI reference](https://proofofwork-agency.github.io/toolpin/docs/reference/cli)
+for the full command list.
+
+## GitHub Actions
+
+Run ToolPin against a committed MCP lockfile:
+
+```yaml
+name: ToolPin
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  toolpin:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: proofofwork-agency/toolpin@v0.2.3
+        with:
+          live: "true"
+          verify: "true"
+          file: mcp-lock.json
+```
+
+The checked-in composite Action builds ToolPin from the action source by
+default, then runs `toolpin ci`. After npm publish, set `toolpin-version` to an
+npm version specifier if you want the Action to install
+`@proofofwork-agency/toolpin` from npm instead.
+
+Recommended CI posture for reviewed lockfiles is `toolpin ci --live --verify`
+for capability drift. Use `--skip-live-verification` only as an explicit downgrade
+when live `tools/list` hashing is unavailable.
+
+## Safety Model
+
+ToolPin is intentionally conservative:
+
+- It fails closed when a client config path is not verified.
+- It keeps structured output on stdout and progress/errors on stderr.
+- It does not print raw secret values during secret audits.
+- It treats score as triage, not proof.
+- It separates evidence tier from metadata completeness.
+- It caps trusted-source conditional entries at 69% until ToolPin verifies
+  artifact proof, such as npm integrity, OCI digest, or MCPB hash evidence.
+- It rejects lockfile drift unless you deliberately review and update the lock.
+
+Verification currently covers install metadata and selected evidence paths:
+npm tarball SRI verification from `registry.npmjs.org`, OCI manifest digest
+resolution, declared attestation metadata, generated capability manifests, and
+optional live `tools/list` hashes. For MCPB artifacts, ToolPin can
+recompute MCPB SHA-256 only for allowlisted HTTPS artifact hosts. See the
+[threat model](https://proofofwork-agency.github.io/toolpin/docs/concepts/threat-model)
+for the exact scope and limits.
+
+## What Exists Now
+
+- Official MCP Registry and Docker MCP Catalog ingestion.
+- ToolPin curated registry source of truth in GitHub:
+  <https://github.com/proofofwork-agency/toolpin/blob/main/registry/v0/servers>
+  with a GitHub Pages static mirror for docs/browsing:
+  <https://proofofwork-agency.github.io/toolpin/registry/v0>
+- Custom registry configuration via `.toolpin/registries.json`.
+- Search ranking over name, title, description, package type, transport, and
+  repository.
+- Install plans and lockfile v2 writes keyed by server/client.
+- Config export for Claude, Cursor, VS Code, Codex, OpenCode, Windsurf, Cline,
+  Continue, Gemini CLI, Zed, Roo Code, and generic sidecar clients.
+- Local policy checks through `.toolpin/policy.json`.
+- Lockfile digest and detached Ed25519 signature verification.
+- Advisory tool-description scans and SARIF output for CI pipelines.
+- Read-only secret hygiene audits for installed client config.
+- Installed inventory, adopt, update, remove, test-installed, and doctor flows.
+- Full-screen terminal UI for browse/install/config workflows.
+
+## Roadmap
+
+The immediate release path is public distribution:
+
+- Publish the npm package with provenance.
+- Keep the GitHub Action pinned and documented for CI adoption.
+- Continue tightening evidence definitions, policy fields, and trust docs.
+
+Longer-term direction:
+
+- Broader verified evidence coverage.
+- Better enterprise policy integration.
+- More client-path verification.
+- Safer secret brokering without plaintext client config.
+- Task-first MCP discovery and stronger tool-description review signals.
+
+See [docs/ROADMAP.md](docs/ROADMAP.md) for project direction.
+
+## Contributing
+
+Contributions are welcome, especially focused fixes with tests. Start with:
+
+```bash
+npm ci
+npm test
+npm run docs:check
+npm run registry:check
+```
+
+Please read [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and
+[CLA.md](CLA.md) before opening larger changes.
+
+## License
+
+ToolPin is distributed under the Apache License 2.0. See [LICENSE](LICENSE).
+
+## Resources
+
+- [Hosted documentation](https://proofofwork-agency.github.io/toolpin/)
+- [CLI reference](https://proofofwork-agency.github.io/toolpin/docs/reference/cli)
+- [Threat model](https://proofofwork-agency.github.io/toolpin/docs/concepts/threat-model)
+- [Client config matrix](docs/client-configs.md)
+- [Catch drift in CI](docs/how-to/catch-drift-in-ci.md)
+- [ToolPin vs. the MCP ecosystem](docs/site/concepts/comparison.md)
+- [Security policy](SECURITY.md)
+- [Disclaimer](DISCLAIMER.md)
+
+## Notice
+
+> **No warranty. You assume all risk.** ToolPin installs and launches
+> third-party MCP servers, including npm packages, Docker images, and remote
+> services. That code can access files, networks, and credentials through the
+> client that runs it. ToolPin's score, evidence tier, and lockfile checks are
+> review aids, not a guarantee that any server is safe. See
+> [DISCLAIMER.md](DISCLAIMER.md) and [docs/threat-model.md](docs/threat-model.md).

package/SECURITY.md

@@ -0,0 +1,61 @@
+# Security Policy
+
+ToolPin is a trust and install-time governance tool for MCP servers. Please do
+not disclose suspected vulnerabilities in public issues until they have been
+triaged.
+
+## Supported Versions
+
+| Version | Supported |
+|---|---|
+| `0.2.x` | Yes (current) |
+| `0.1.x` | Limited |
+| `< 0.1.0` | No |
+
+Pre-1.0 releases may change lockfile, policy, and CLI behavior. Security fixes
+will be released on the latest minor line unless a backport is explicitly
+announced.
+
+## Reporting a Vulnerability
+
+Use GitHub private vulnerability reporting when it is available for this
+repository. If private reporting is not available, email the maintainer listed
+for the project and include `ToolPin security report` in the subject.
+
+Please include:
+
+- A concise description of the issue and affected command or file.
+- Reproduction steps, preferably against a minimal `mcp-lock.json` or registry
+  fixture.
+- The expected security boundary and the observed bypass.
+- Whether any secrets, signatures, lockfiles, or client configs were exposed.
+
+Do not include live secrets, private signing keys, or production client config
+files. Redact values before attaching logs.
+
+## Response Targets
+
+- Initial acknowledgement: 5 business days.
+- Triage decision: 10 business days after enough reproduction detail is
+  available.
+- Coordinated disclosure target: 30 days for accepted high-impact issues, or a
+  mutually agreed timeline when a fix needs upstream coordination.
+
+## Security Scope
+
+In scope:
+
+- Lockfile integrity or signature verification bypasses.
+- `toolpin ci` false positives that allow drift or tampering to pass.
+- Policy enforcement bypasses in `install`, `ci`, or TUI install flows.
+- Plaintext secret disclosure in logs, reports, or generated config.
+- Registry metadata parsing bugs that lead to unsafe config generation.
+
+Out of scope unless they lead to one of the above:
+
+- Prompt-injection bypasses of advisory text scans.
+- Vulnerabilities in third-party MCP servers installed through ToolPin.
+- Runtime sandbox escapes after an MCP server is already running.
+- Social engineering, spam, or denial-of-service against public infrastructure.
+
+See `docs/threat-model.md` for the current security model and non-goals.