peerband 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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/NOTICE

@@ -0,0 +1,12 @@
+PeerBand
+Copyright 2026 Kirill Shvidler
+
+This is an unofficial project, not affiliated with Herdr or Amazon.
+The Herdr protocol schema fixture is derived from herdrdev/herdr 0.9.3,
+copyright its contributors, under Apache License 2.0.
+https://github.com/herdrdev/herdr
+
+Original project code is licensed under Apache License 2.0.
+Bundled dependencies (ws, ajv, ajv-formats) retain their own licenses; see
+package-lock.json and the corresponding package license files. Herdr and
+Amazon names identify integration targets and do not imply endorsement.

package/README.md

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+# PeerBand
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A direct line to your coding agents.** PeerBand lets you reach the agents running in [Herdr](https://herdr.dev) from any MCP client (Claude, ChatGPT, your own tools) through your PeerBand account. This repository is the open-source client: the `peerband` command-line tool and the Herdr plugin. It runs on your machine and connects out to the PeerBand relay; nothing connects in.
+
+```
+MCP client --> PeerBand relay <== outbound WebSocket == peerband connector --> Herdr
+ (Claude, ...)  (peerband.com)                          (on your machine)     (your agents)
+```
+
+Your MCP client can list agents, read their status and bounded recent output, and (only if you opt in) send them a message. This project is unofficial and is not affiliated with Herdr or Amazon.
+
+## Requirements
+
+- Node.js 22.13 or newer
+- Herdr 0.9.3 or newer (needed for the Relay tab)
+- A PeerBand account (peerband.com)
+
+## Install
+
+macOS and Linux:
+
+```sh
+curl -fsSL https://peerband.com/install.sh | sh
+```
+
+Windows PowerShell:
+
+```powershell
+irm https://peerband.com/install.ps1 | iex
+```
+
+Or with npm directly:
+
+```sh
+npm install -g peerband
+```
+
+The installers check Node, install the CLI, run `peerband login` (which opens your browser), and set up the Herdr plugin when Herdr is present.
+
+Headless machine or CI with no browser? Pass a one-time grant from the PeerBand dashboard instead: `curl -fsSL https://peerband.com/install.sh | sh -s -- --grant GRANT --name "my-server"`, or on Windows `$env:PEERBAND_GRANT = 'GRANT'; irm https://peerband.com/install.ps1 | iex`.
+
+> PeerBand is not published to npm yet. To try a build, run `npm pack` in this repository and install with `PEERBAND_PACKAGE=/path/to/peerband-0.1.0.tgz` (a tarball path or git URL) set when running the installer.
+
+## Quickstart
+
+1. Install the CLI (above).
+2. `peerband login` opens your browser. Sign in to PeerBand and confirm the code shown in your terminal.
+3. `peerband herdr install` to add the plugin to Herdr.
+4. `peerband relay` to open the PeerBand Relay tab, then press Space to connect.
+5. Add the MCP server URL that `peerband relay` and `peerband status` print (`https://mcp.peerband.com/mcp`) to your MCP client: a custom connector in ChatGPT or Claude, or `claude mcp add --transport http peerband https://mcp.peerband.com/mcp` in Claude Code. Sign in and approve access when the client asks.
+
+## Logging in
+
+```
+$ peerband login
+To sign in, open this page in your browser:
+
+  https://peerband.com/device?code=WDJB-MJHT
+
+and confirm this code:   WDJB-MJHT
+
+Opened your browser.
+⠋ Waiting for approval… (Ctrl+C to cancel)
+```
+
+`peerband login` requests a short code from the server, opens the link, and polls until you approve it in your PeerBand account. Compare the code in the browser with the one in your terminal and only approve a request you just started yourself. The credential is stored in the config home (see below) and never printed; the secret device code is never shown.
+
+- The browser is not opened over SSH, without a display, when output is piped, or with `--no-browser`. The link and code are still printed: open the link on any device where you are signed in to PeerBand.
+- **Headless or CI:** create a one-time grant in the dashboard and run `peerband login --grant GRANT` (or set `PEERBAND_GRANT` to keep it out of your shell history).
+- Codes expire after about 10 minutes; run `peerband login` again. Ctrl+C cancels (exit 130). A server without browser sign-in answers with a hint to use `--grant`.
+- `--name NAME` sets the machine name shown in the dashboard (default: hostname); `--server URL` or `PEERBAND_SERVER` targets another server.
+
+## The Relay tab
+
+The plugin adds a persistent tab titled `PeerBand Relay [On]` or `[Off]` that shows your account, connection state and a metadata-only activity log.
+
+- **Space** or **Enter** (or a click on the control box) toggles the connection.
+- **Q**, **Esc** or **Ctrl+C** asks to close the tab; press it again to confirm. Closing it disconnects the relay.
+- The tab is reopened when Herdr starts. `peerband relay` opens or focuses it at any time.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `peerband login` | Sign in through your browser. Flags: `--no-browser`, `--name NAME`, `--server URL`; headless/CI: `--grant GRANT` |
+| `peerband logout` | Stop a running relay and delete the local credential. Does not revoke it on the server |
+| `peerband status` | Show login, relay and Herdr state. `--json` for machine-readable output |
+| `peerband connect` | Run the connector in the foreground. Flags: `--runtime herdr\|mock`, `--enable-writes`, `--config PATH`, `--server URL` |
+| `peerband relay` | Open or focus the Relay tab in Herdr |
+| `peerband herdr install` | Install (or update) the Herdr plugin |
+| `peerband herdr uninstall` | Stop the relay, remove the plugin and its `settings.json` |
+| `peerband --version`, `help [command]` | Version and help |
+
+Exit codes: 0 success, 1 failure, 2 usage error, 3 not logged in, 130 interrupted (Ctrl+C in `peerband connect`).
+
+## Configuration
+
+The config home is `PEERBAND_CONFIG_HOME` if set; otherwise `%APPDATA%\peerband` on Windows, and `$XDG_CONFIG_HOME/peerband` or `~/.config/peerband` elsewhere. It holds `credentials.json`, the relay state (`relay-state.json`, `relay-tab.json`), the receipt store (`state/receipts.json`) and the optional `connector.json`. `peerband connect` also reads `PEERBAND_RUNTIME` and `PEERBAND_CONNECTOR_CONFIG` (the `--runtime` and `--config` defaults).
+
+`PEERBAND_SERVER` (or `--server`) overrides the default server `https://peerband.com`. Plain `http:` is accepted only for loopback hosts.
+
+Optional `connector.json`:
+
+```json
+{
+  "allowedAgents": ["claude"],
+  "allowedWorkspaces": ["my-project"],
+  "enableWrites": false,
+  "stateDirectory": "/path/to/state",
+  "herdr": {
+    "socketPath": "/path/to/herdr-api.sock",
+    "schemaPath": "/path/to/herdr-api.schema.json",
+    "binary": "/path/to/herdr",
+    "machineId": "my-laptop",
+    "timeoutMs": 5000
+  }
+}
+```
+
+All fields are optional. `allowedAgents` and `allowedWorkspaces` restrict what MCP clients can see; `stateDirectory` moves the receipt store (default `state/` in the config home). The `herdr` block is only needed when Herdr is not on `PATH` or you target a specific session.
+
+## Security model
+
+- **Outbound only.** The connector dials the relay over a WebSocket; it opens no listening port.
+- **Credential on disk** is stored in `credentials.json`, readable only by your user (mode 0600 inside a 0700 directory).
+- **Read-only by default.** Listing agents, status and bounded, sanitized output are available. Sending messages requires `--enable-writes` or `"enableWrites": true`, and each send needs an idempotency key.
+- **Metadata-only activity.** The Relay tab and receipts record what happened (tool, target, outcome), not prompts or output.
+- **Logout does not revoke.** `peerband logout` only deletes the local file. To revoke a machine, remove it in the PeerBand dashboard.
+
+Agent output can contain secrets, and redaction is best effort. See [SECURITY.md](SECURITY.md) to report a vulnerability.
+
+## How Herdr finds Node
+
+Herdr may resolve a different (older) `node` than your shell. `peerband herdr install` therefore records the absolute path of the Node that ran it, in the plugin's `settings.json` (in the directory printed by `herdr plugin config-dir peerband`), along with `PEERBAND_CONFIG_HOME` when it is set. The plugin launcher uses that Node. (The Herdr binary is not recorded: Herdr sets `HERDR_BIN_PATH` for plugin processes itself.) `peerband herdr uninstall` deletes this file. If you change your Node installation, rerun `peerband herdr install`.
+
+## Troubleshooting
+
+- **"PeerBand needs Node.js 22.13 or newer" inside Herdr.** Run `peerband herdr install` from a shell whose `node --version` is 22.13+.
+- **The Relay tab does not open.** Check `peerband status` for the plugin, run `herdr plugin list` (look for a line like `- peerband (PeerBand) enabled [github:kshvidler/peerband-cli@v0.1.0]`), and confirm Herdr is 0.9.3 or newer. Then `peerband relay`.
+- **Windows: Herdr cannot see files in AppData.** Set `PEERBAND_CONFIG_HOME` to a plain folder (for example `D:\peerband`), log in again, and rerun `peerband herdr install` so the plugin picks it up.
+- **The plugin shows up in other Herdr sessions too.** Herdr's plugin registry is per user, shared by all Herdr sessions, so installing, linking or uninstalling PeerBand affects every session.
+- **"not logged in" (exit 3).** Run `peerband login`.
+- **Revoked.** The machine was removed in the dashboard. Run `peerband login` again.
+- **SSH or a headless machine: no browser opens.** That is intended. Run `peerband login --no-browser`, open the printed link on a device where you are signed in to PeerBand (your laptop or phone), and confirm the code. Or skip the browser entirely with `peerband login --grant GRANT` using a grant from the dashboard.
+- **"The code expired."** You have about 10 minutes to approve. Run `peerband login` again.
+- **"This server doesn't support browser sign-in yet."** Use `peerband login --grant GRANT`.
+- **The browser did not open.** Open the printed link manually; the code is part of the link.
+
+## Protocol
+
+JSON Schemas for the relay WebSocket messages, the enrollment API and browser device login are in [`protocol/`](protocol/).
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE). Contributions: [CONTRIBUTING.md](CONTRIBUTING.md).

package/SECURITY.md

@@ -0,0 +1,27 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please report security issues privately using GitHub's **Report a vulnerability** button on the repository's Security tab (GitHub Security Advisories). Do not open a public issue for a vulnerability.
+
+Include the affected version (`peerband --version`), your operating system and Node.js version, and steps to reproduce. Do not include credentials, enrollment grants or private terminal output; redact them first.
+
+## Scope
+
+This repository is the PeerBand client: the `peerband` CLI, the connector that dials the relay, and the Herdr plugin. In scope:
+
+- credential storage and handling (`credentials.json`, enrollment grants)
+- the outbound relay connection and request handling
+- the opt-in write path (`send_agent_message`) and its authorization checks
+- the installers (`install/install.sh`, `install/install.ps1`)
+- the Herdr plugin launcher and process ownership
+
+## Design notes
+
+- The connector only makes outbound connections. It never listens for inbound ones.
+- The credential file is created user-only (mode 0600 in a 0700 directory).
+- Writes are disabled unless you opt in with `--enable-writes` or `enableWrites` in `connector.json`.
+- The activity log is metadata only; prompts and agent output are not persisted.
+- `peerband logout` deletes the local credential but does not revoke it. Revoke machines from your PeerBand dashboard.
+
+Agent output returned to an MCP client may still contain secrets; redaction is best effort.