lockbox-mcp 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 2026 Eduardo Rosostolato
+
+   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

@@ -1,3 +1,467 @@
-# Temporary Holding Version
+# Lockbox
 
-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.
+**Let your AI agent set up API keys without ever seeing them.**
+
+[![CI](https://github.com/rosostolato/lockbox-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/rosostolato/lockbox-mcp/actions/workflows/ci.yml)
+[![License: Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Node 20+](https://img.shields.io/badge/node-20%2B-blue.svg)](https://nodejs.org/)
+
+You ask Claude, Cursor or any MCP client to *"put the Stripe key in our .env"* — or in Secret
+Manager, Vercel, your own API. The agent describes **where** it goes. You read that in Lockbox's
+own window and paste the value there. The key goes straight to the destination and never
+enters the chat, the prompt or the logs.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/images/paste-dark.png">
+    <img src="docs/images/paste-light.png" width="420" alt="Lockbox's window: a red PRODUCTION band, 'Paste STRIPE_SECRET_KEY', the destination 'Production env · .env.production', a masked field confirming a live key, a Continue button and a closed 'See exactly what will be sent'">
+  </picture>
+</p>
+
+1. **The agent describes the destination.** A file, a program such as `gcloud`, or an HTTPS
+   request, with `{{secret}}` where the value goes. The tool has no field that could carry a
+   value.
+2. **You check and paste.** Lockbox's local window shows where the key goes in one line, warns
+   about anything new or odd, and checks the key's format. The exact request is one click
+   away.
+3. **Lockbox sends it.** The agent only learns `STORED` and a reference. It never sees the key.
+
+```bash
+claude mcp add lockbox -e LOCKBOX_ENV_ALLOWED_ROOTS="$PWD" -- npx -y lockbox-mcp serve
+```
+
+Then ask your agent: *"store my Stripe test key in .env"*.
+
+---
+
+## Install
+
+Lockbox is a stdio MCP server, so you do not run it yourself — your MCP client starts it, the
+same way it starts any other npm-published server. Requires Node 20+.
+
+### Claude Code
+
+```bash
+cd ~/some/project
+claude mcp add lockbox -e LOCKBOX_ENV_ALLOWED_ROOTS="$PWD" -- npx -y lockbox-mcp serve
+```
+
+Add `-s project` to record it in the repository's `.mcp.json` instead of your own config.
+
+### Any other client (Claude Desktop, Cursor, Windsurf, VS Code, Zed…)
+
+Drop this into the client's MCP configuration — the `mcpServers` block is the same shape
+everywhere:
+
+```json
+{
+  "mcpServers": {
+    "lockbox": {
+      "command": "npx",
+      "args": ["-y", "lockbox-mcp", "serve"],
+      "env": {
+        "LOCKBOX_ENV_ALLOWED_ROOTS": "/absolute/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+Prefer a pinned install to an ephemeral one:
+
+```bash
+npm install -g lockbox-mcp
+# then use `lockbox-mcp serve` as the command, with no npx
+```
+
+The package is published to npm, unscoped, as `lockbox-mcp`.
+
+**Set `LOCKBOX_ENV_ALLOWED_ROOTS`.** File destinations refuse to write outside those
+directories, and they default only to the server's working directory. Everything else is
+optional — see [Configuration](#configuration).
+
+Destinations behind a login (Google Secret Manager, Vercel, GitHub) are reached through their
+own CLI, which uses the login you already have — `gcloud`, `vercel`, `gh`. See
+[Destinations](#destinations).
+
+### First run
+
+Ask your agent for something like *"store my Stripe test key in .env"*. Lockbox opens its
+window on your machine; the agent does not receive that link. The band at the top tells you
+the environment at a glance, and the field tells you whether the key looks right before you
+send it.
+
+<table>
+  <tr>
+    <td width="33%" valign="top">
+      <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="docs/images/warning-dark.png">
+        <img src="docs/images/warning-light.png" alt="A test key pasted for a production destination: 'Looks like a test key, but this goes to production.'">
+      </picture>
+      <p><strong>Catches the wrong key.</strong> A <code>test</code> key headed for
+      production gets flagged in the window. The check runs locally and never shows the
+      value.</p>
+    </td>
+    <td width="33%" valign="top">
+      <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="docs/images/confirm-dark.png">
+        <img src="docs/images/confirm-light.png" alt="Second step: 'Save to .env.production?' with a field where .env.production:STRIPE_SECRET_KEY has been typed">
+      </picture>
+      <p><strong>Confirms before sending.</strong> Nothing is sent until you type where it
+      goes: the host, the program or the file.</p>
+    </td>
+    <td width="33%" valign="top">
+      <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="docs/images/saved-dark.png">
+        <img src="docs/images/saved-light.png" alt="'Saved' with the destination and the reference .env.production:STRIPE_SECRET_KEY">
+      </picture>
+      <p><strong>Tells the agent only "stored".</strong> Lockbox wipes the value and hands back
+      a reference such as the file and variable.</p>
+    </td>
+  </tr>
+</table>
+
+<kbd>Enter</kbd> continues and <kbd>Esc</kbd> cancels. The link works once: if anything
+opened it before your browser did, Lockbox shows an alarm and a Cancel button instead of the
+request. Lockbox's stderr carries structured audit JSON; nothing else is expected of you in the
+terminal.
+
+---
+
+## What Lockbox solves
+
+It removes an entire class of failures caused by the agent **knowing** the secret.
+With Lockbox in the loop, a credential does not pass through:
+
+- LLM prompts or conversation history
+- MCP tool arguments or tool results
+- agent memory or generated code
+- shell command arguments or process argv
+- logs, debug traces or telemetry
+- URLs
+- model-visible command output
+
+## What Lockbox does **not** solve
+
+Lockbox does not make an AI agent trustworthy, and it is not "safe AI". It does not
+guarantee that the agent picked the right destination, that it understood you, that it
+is free of prompt injection, that the destination is itself secure, that your machine is
+uncompromised, or that a credential cannot be misused later by software that legitimately
+receives it.
+
+There are two separate problems here:
+
+| Question | Lockbox's answer |
+| --- | --- |
+| Should the agent know the secret? | No. |
+| Should the agent decide alone where the secret goes? | Not without human authorization. |
+
+Lockbox answers those two. It does not claim to answer the rest.
+
+---
+
+## Trust model
+
+```text
+Trusted with the credential value:
+
+  The human at the keyboard
+  Lockbox's secure input UI       (loopback only, in your control)
+  Lockbox's secure input broker   (this process)
+  The destination you approved    (a file, a program, an HTTPS endpoint)
+
+NOT trusted with the credential value:
+
+  The LLM
+  The agent / MCP client
+  The conversation
+  The prompt and any repository content it read
+  Generated code
+  Logs, telemetry, crash reports
+```
+
+Lockbox's runtime dependency list is one package (`zod`, for input validation). The MCP
+protocol is implemented in-tree rather than through the official SDK, which would add ~90
+packages — including HTTP servers and an OAuth stack — to a process that holds plaintext
+credentials.
+
+This diagram does not claim the trusted components are invulnerable. It says where the
+credential is *allowed* to exist. Lockbox is security-sensitive software: if Lockbox itself is
+malicious or compromised, the boundary is gone. Its source, dependencies and releases
+deserve the scrutiny you would give any credential-handling tool.
+
+---
+
+## The two flows
+
+**The secret flow** — the human's path, which the model cannot observe:
+
+```text
+Human ─▶ Lockbox secure UI (127.0.0.1) ─▶ Broker ─▶ approved definition ─▶ Destination
+```
+
+**The agent flow** — everything the model sees:
+
+```text
+LLM ─▶ MCP client ─▶ Lockbox MCP server ─▶ non-sensitive result metadata
+```
+
+The MCP tool schema has no property capable of carrying a credential. That is structural,
+not a prompt instruction: there is no `value`, `secret_value`, `password`, `token`,
+`content` or `raw_secret` field to abuse, closed schemas reject unknown properties, and
+arguments are screened for credential-shaped values before they are parsed.
+
+### What the agent calls
+
+```json
+{
+  "destination": "custom",
+  "name": "STRIPE_SECRET_KEY",
+  "target": {
+    "definition": {
+      "kind": "command",
+      "label": "Google Secret Manager",
+      "executable": "/opt/homebrew/bin/gcloud",
+      "args": ["secrets", "versions", "add", "stripe-secret-key",
+               "--project", "acme-prod", "--data-file=-"],
+      "stdin": "{{secret}}"
+    }
+  },
+  "environment": "production",
+  "description": "Stripe production API key"
+}
+```
+
+Lockbox replies with a `request_id`, a risk classification and the normalized destination —
+and opens its own authorization window on your machine. The agent polls `secret_status`.
+`destination: "saved:<name>"` reuses a destination the human saved earlier.
+
+**The agent does not get the authorization link.** That link is a capability: anything
+holding it can complete the human's half of the flow, and an agent with a shell or an HTTP
+tool is precisely the threat model. Lockbox hands it straight to your browser. Set
+`LOCKBOX_DISCLOSE_AUTHORIZATION_URL=true` if your setup needs the agent to relay the link (for
+example, a remote or headless session) — and understand that this lets a compromised agent
+authorize its own request.
+
+**The link works once.** Opening it trades it for an `HttpOnly; SameSite=Lax` session cookie
+scoped to that request and redirects to an address with no token in it; every later page and
+form needs the cookie. A second opening of the same link gets an alarm page ("This link was
+already opened") with a Cancel button, never the request. So a copy left in browser history,
+a process list or a log is dead once you open it, and one used by someone else first is
+visible to you.
+
+**Logs never hold the identity phrase, and hold the link only as a last resort.** MCP hosts
+save server stderr to files any process running as you can read (Claude Desktop under
+`~/Library/Logs/Claude/`, Claude Code under its cache directory), so the audit record carries
+a short fingerprint of the link instead. The full link is logged only when no browser could
+be opened (`LOCKBOX_OPEN_BROWSER=false`, too many windows, or the opener failed), because the
+operator then has no other way in.
+
+| Tool | Purpose |
+| --- | --- |
+| `secret_store` | Create a credential request. Returns non-sensitive metadata and a request id. |
+| `secret_status` | Poll a request. Never returns credential material. |
+| `secret_cancel` | Cancel a pending request; any entered value is destroyed. |
+| `secret_revise` | Invalidate an authorization and start a new one. Nothing is edited in place. |
+| `secret_destinations` | The definition contract, worked examples, and the user's saved destinations. |
+
+### What the human sees
+
+Stage A shows the credential name and **one destination line** — the definition's label and
+its host, program or file — plus a line for anything worth a second look: a host never
+used before, a host spelled with non-ASCII characters, an IP address instead of a name, a
+program outside the system folders, a saved destination that changed. The full request (the
+URL, every header and the body; or the program, each argument and stdin; or the file and
+its content) sits behind **"See exactly what will be sent"**, closed by default, with the
+canonical JSON and its hash. Every custom destination needs a second confirmation in Stage
+B, after entry and before anything is sent: the human types the host, the program name or
+the file (`.env:API_TOKEN` for a variable), and the server checks it. This is an attention
+check, not authentication: the expected text is on the page. What keeps a second party out
+of Stage B is the session cookie. The value is never displayed back.
+
+POSTs are refused unless they come from Lockbox's own page (`Origin` and `Sec-Fetch-Site`), and
+every response sets `Cross-Origin-Opener-Policy` and `Cross-Origin-Resource-Policy` to
+`same-origin`. The credential field asks browser and third-party password managers not to
+save it.
+
+The page runs one inline script under a per-response CSP nonce. It describes the value's
+shape (length, a `live`/`test` marker against the destination's environment, stray
+whitespace), counts down the expiry and maps <kbd>Esc</kbd> to Cancel. The CSP gives it no
+network access, and Cancel is a separate form, so cancelling never sends the value. Without
+JavaScript the page still works, minus those three aids.
+
+The page the human reads and the operation the executor performs are the *same immutable
+object* — there is no separate "display destination". Any change to destination, project,
+secret name, operation, write mode or adapter invalidates the authorization and requires a
+new one.
+
+---
+
+## Destinations
+
+There are no built-in destinations. The agent writes a **definition** — JSON with
+`{{secret}}` exactly once where the value goes, and optionally `{{name}}` for the credential
+name — and the human approves it as rendered. Three kinds:
+
+| Kind | What it does | Rules |
+| --- | --- | --- |
+| `file` | Writes a local file. Mode `env` sets one variable in a `.env` and keeps every other line; `create` and `replace` write the whole template. | Inside `LOCKBOX_ENV_ALLOWED_ROOTS`; `.env` / `.env.<suffix>` names only by default; no symlinks; atomic `0600`; git-tracked files refused, and a new file must be git-ignored. |
+| `command` | Runs a program with fixed arguments and hands it the value on **stdin**. | Absolute path, pinned by real path and SHA-256 at approval and re-checked before it runs; no shell; minimal environment; `{{secret}}` never in an argument; timeout. The agent learns only the exit status. |
+| `http` | Sends one HTTPS request. | `https` only; `POST`/`PUT`/`PATCH`; `{{secret}}` only in the body or a header value, never the URL; host resolved once and pinned; private and metadata addresses refused by default; redirects not followed. The agent learns the status and an optional reference read from the response, never the response. |
+
+```jsonc
+// A .env variable
+{ "kind": "file", "label": "Project .env", "path": ".env",
+  "template": "{{name}}={{secret}}", "mode": "env" }
+
+// Google Secret Manager, through gcloud's own login
+{ "kind": "command", "label": "Google Secret Manager", "executable": "/opt/homebrew/bin/gcloud",
+  "args": ["secrets", "versions", "add", "stripe-secret-key", "--project", "acme-prod", "--data-file=-"],
+  "stdin": "{{secret}}" }
+
+// An HTTPS API that needs no other token
+{ "kind": "http", "label": "Internal secrets API",
+  "url": "https://secrets.example.com/v1/projects/acme/secrets", "method": "POST",
+  "headers": { "Content-Type": "application/json" },
+  "body": { "type": "json", "value": { "name": "{{name}}", "value": "{{secret}}" } },
+  "reference": "$.id" }
+```
+
+**Saved destinations.** At Stage B the human can tick *Save as a trusted destination* and
+name it; it is saved only if the write succeeds. Next time the agent asks for
+`saved:<name>`, and the window reads "Saved · name · host". Each entry is pinned to the
+SHA-256 of its canonical JSON: if the file is edited, the window says *Changed since you saved
+it* and reviews it as new. The store lives at `$XDG_CONFIG_HOME/lockbox/destinations.json`
+(mode `0600`), written only by Lockbox; the window can forget an entry.
+
+**What is not covered yet.** An HTTPS API that needs its own token besides the credential
+(Vercel, GitHub, Doppler REST) is reached through its CLI instead: the agent cannot supply
+that token, and Lockbox does not ask for two values in one request. Firestore has no CLI that
+writes a single field cleanly, so it has no recipe today.
+
+---
+
+## Security assumptions and limitations
+
+Stated plainly, because a security tool that oversells itself is worse than none:
+
+- **The broker process sees the secret.** That is the point: something must, or storage is
+  impossible. The guarantee is that only the minimal trusted transport and destination
+  components do.
+- **Memory erasure is best-effort.** `SecretBuffer` wipes the exact `Buffer` it owns, and
+  the HTTP body is percent-decoded into buffers Lockbox wipes too. But any conversion to a
+  JavaScript string — which writing a `.env` line requires — creates an immutable copy that
+  V8 may keep until garbage collection, and that copy cannot be wiped. Lockbox minimizes those
+  conversions rather than pretending they do not happen.
+- **The UI is loopback HTTP.** Any process running as your user on your machine can reach
+  it, and any such process could also imitate it. Lockbox refuses to bind anywhere but
+  loopback. Request pages show a per-process identity phrase, but it is no longer logged,
+  so today there is no second channel to compare it against: treat it as decoration, not
+  as anti-spoofing. Withholding the link and making it single-use raise the bar; they do
+  not stop a process that wins the race to the link, reads the browser's memory, or binds
+  its own lookalike port.
+- **An agent with an unrestricted shell is out of reach.** Running as you, it can read
+  files Lockbox writes (including a `.env` destination), browser state and MCP logs. No page
+  design fixes that. Run the agent sandboxed — for example Claude Code's sandboxed Bash,
+  with loopback and the MCP log directories outside what it may reach.
+- **Lockbox sends where you approved, not where it is wise to.** An agent writes the
+  definition, so a hijacked agent can propose an attacker's endpoint. Lockbox shows the host
+  first, flags it when it is new or disguised, and makes you type it — but a human who
+  approves what they did not read has approved it.
+- **A definition is only as safe as what it runs.** A `command` destination runs the
+  program you approved with the value on stdin; what that program then does with it is
+  outside Lockbox.
+- **Timeouts are enforced by Lockbox.** HTTP requests and commands are cut off at
+  `LOCKBOX_ADAPTER_TIMEOUT_SECONDS`, and a command is killed with `SIGKILL`.
+- **Preflight is best-effort.** A provider that is unreachable at preflight is reported as
+  unavailable rather than guessed at.
+- **Crash semantics.** A crash between the provider write and the response can leave a
+  credential written with no local record of success. Lockbox reports the request as failed;
+  the destination is the source of truth.
+
+---
+
+## Local development
+
+```bash
+git clone https://github.com/rosostolato/lockbox-mcp && cd lockbox-mcp
+npm install
+npm run check      # typecheck + lint + format + tests
+npm run build
+```
+
+To point a client at your checkout, use `node /path/to/lockbox-mcp/dist/index.js` as the
+command instead of `npx`.
+
+## Configuration
+
+Configuration is read from Lockbox's own environment — never from tool arguments, so an agent
+cannot relax a policy:
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `LOCKBOX_REQUEST_TTL_SECONDS` | `300` | Request expiry. |
+| `LOCKBOX_ADAPTER_TIMEOUT_SECONDS` | `30` | Upper bound on one destination write. |
+| `LOCKBOX_STAGE_B_FOR_MEDIUM` | `true` | Require confirmation for medium-risk operations. |
+| `LOCKBOX_UI_HOST` / `LOCKBOX_UI_PORT` | `127.0.0.1` / ephemeral | Secure UI bind address. Loopback only; anything else refuses to start. |
+| `LOCKBOX_OPEN_BROWSER` | `true` | Open the authorization window automatically. |
+| `LOCKBOX_DISCLOSE_AUTHORIZATION_URL` | `false` | Return the authorization link to the agent. |
+| `LOCKBOX_ENV_ALLOWED_ROOTS` | current directory | Roots `file` destinations may write inside. |
+| `LOCKBOX_ALLOW_GIT_TRACKED_ENV` | `false` | Permit writing into a git-tracked, or new and un-ignored, file. |
+| `LOCKBOX_ENV_ALLOW_ANY_FILENAME` | `false` | Permit file names other than `.env` / `.env.<suffix>`. |
+| `LOCKBOX_CUSTOM_DESTINATIONS` | `save` | `save` lets the human save approved destinations; `once` approves every request on its own. |
+| `LOCKBOX_CUSTOM_KINDS` | `http,command,file` | Kinds an agent may define. |
+| `LOCKBOX_CUSTOM_HTTP_HOSTS` | any | Comma-separated allowlist of HTTPS hosts; empty means any host, still reviewed. |
+| `LOCKBOX_CUSTOM_HTTP_ALLOW_PRIVATE` | `false` | Permit hosts that resolve to loopback, private or link-local addresses. |
+| `LOCKBOX_CUSTOM_STORE_PATH` | `$XDG_CONFIG_HOME/lockbox/destinations.json` | Where saved destinations live. |
+
+## Tests
+
+```bash
+npm test                # everything
+npm run test:security   # the adversarial suite only
+npm run check           # what CI runs
+```
+
+The security suite is a product requirement, not a nicety. It contains canary-leakage
+detection across every observable channel, malicious-agent tests, prompt-injection
+fixtures, TOCTOU and replay tests, 100-way concurrency stress, race conditions, crash
+paths (including a real `SIGKILL` mid-write), provider-failure simulation, UI checks and
+fuzzing. A release is blocked if any canary leaks, any authorization bypass succeeds, any
+post-approval mutation succeeds, any completed request is replayable, any secret crosses a
+request boundary, any raw provider error reaches MCP, or any high-risk operation skips
+confirmation.
+
+See [`docs/SECURITY_MODEL.md`](docs/SECURITY_MODEL.md) for the invariant-to-test map.
+
+## Project status
+
+Version 0.1.0, built to [`SPEC.md`](SPEC.md), which stays in the repository as the
+authoritative description of the intended behaviour. The implementation is TypeScript on
+Node; it was ported from an equivalent Python implementation, which remains in the git
+history. Every substantial module and test
+cites the section it implements, so a reviewer can check the code against the requirement
+rather than against a summary of it.
+
+The MVP is complete and the full suite — including the adversarial one — passes. What
+remains before anyone should rely on it in anger: independent review, human-factor testing
+of the confirmation UI (SPEC.md §35), and signed release artefacts (§43).
+
+## Contributing
+
+Security is the product here, so the bar for changes is specific rather than bureaucratic:
+
+- A change that touches credential handling, authorization or the MCP surface needs a test
+  that *attempts to break* the invariant it affects, not only one that shows it working.
+- Never weaken a security test to make a suite pass. If a test reveals an architectural
+  flaw, the architecture is what changes.
+- New runtime dependencies in the core are opposed by default. The broker is the trusted
+  computing base for credential material; provider SDKs belong behind an optional extra.
+- Run `npm run check` before opening a pull request.
+
+Found a vulnerability? Please report it privately through GitHub's security advisories
+rather than opening a public issue.
+
+## License
+
+[Apache License 2.0](LICENSE) © 2026 Eduardo Rosostolato.