keyward 0.0.1__py3-none-any.whl

keyward/__init__.py

@@ -0,0 +1,7 @@
+"""Local secret broker that keeps API keys out of files AI agents can read."""
+
+__version__ = "0.0.1"
+
+from keyward.inject import ActivateResult, DaemonNotRunning, activate
+
+__all__ = ["ActivateResult", "DaemonNotRunning", "__version__", "activate"]

keyward/__main__.py

@@ -0,0 +1,4 @@
+from keyward.cli import app
+
+if __name__ == "__main__":
+    app()

keyward/agent.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import os
+import plistlib
+import subprocess
+from pathlib import Path
+
+LABEL = "com.keyward.daemon"
+
+
+def plist_path() -> Path:
+    return Path.home() / "Library" / "LaunchAgents" / f"{LABEL}.plist"
+
+
+def log_dir() -> Path:
+    return Path.home() / "Library" / "Logs" / "keyward"
+
+
+def _uid() -> int:
+    if not hasattr(os, "getuid"):
+        raise RuntimeError("LaunchAgent install is macOS-only; not supported on this OS.")
+    return os.getuid()
+
+
+def _bootout() -> None:
+    # Idempotent: non-zero exit when not loaded is fine.
+    subprocess.run(
+        ["launchctl", "bootout", f"gui/{_uid()}/{LABEL}"],
+        check=False,
+        capture_output=True,
+    )
+
+
+def _bootstrap(plist: Path) -> None:
+    result = subprocess.run(
+        ["launchctl", "bootstrap", f"gui/{_uid()}", str(plist)],
+        check=False,
+        capture_output=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"launchctl bootstrap failed ({result.returncode}): "
+            f"{result.stderr.decode().strip() or result.stdout.decode().strip()}"
+        )
+
+
+def _write_plist(plist: Path, python_executable: str) -> None:
+    plist.parent.mkdir(parents=True, exist_ok=True)
+    log_dir().mkdir(parents=True, exist_ok=True)
+    contents = {
+        "Label": LABEL,
+        "ProgramArguments": [python_executable, "-m", "keyward.daemon"],
+        "RunAtLoad": True,
+        "KeepAlive": True,
+        "StandardOutPath": str(log_dir() / "daemon.out"),
+        "StandardErrorPath": str(log_dir() / "daemon.err"),
+        # Don't run faster than once every 5s if the daemon crash-loops.
+        "ThrottleInterval": 5,
+    }
+    with plist.open("wb") as f:
+        plistlib.dump(contents, f)
+
+
+def install(python_executable: str) -> Path:
+    """Write the LaunchAgent plist and load it. Idempotent."""
+    path = plist_path()
+    _write_plist(path, python_executable)
+    _bootout()
+    _bootstrap(path)
+    return path
+
+
+def uninstall() -> bool:
+    """Unload and remove the LaunchAgent. Returns True if a plist was removed."""
+    path = plist_path()
+    _bootout()
+    if path.exists():
+        path.unlink()
+        return True
+    return False
+
+
+def restart() -> None:
+    """Kickstart the LaunchAgent, forcing it to reload config and secret cache."""
+    subprocess.run(
+        ["launchctl", "kickstart", "-k", f"gui/{_uid()}/{LABEL}"],
+        check=False,
+        capture_output=True,
+    )
+
+
+def is_installed() -> bool:
+    return plist_path().exists()

keyward/cli.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import platform
+import signal
+import subprocess
+import sys
+import time
+
+import typer
+
+from keyward import __version__, agent, store
+from keyward.config import daemon_file, ensure_dirs
+from keyward.discovery import live_daemon_info
+
+app = typer.Typer(
+    name="keyward",
+    help="Local secret broker. Keeps API keys out of files AI agents can read.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _version_cb(value: bool) -> None:
+    if value:
+        typer.echo(f"keyward {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_cb,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    pass
+
+
+def _hint_restart_if_running() -> None:
+    if live_daemon_info() is not None:
+        typer.echo("hint: a daemon is running. Run 'keyward restart' to reload the change.")
+
+
+@app.command()
+def init(
+    uninstall: bool = typer.Option(False, "--uninstall", help="Remove the login agent."),
+) -> None:
+    """Create config/state dirs and install the daemon as a login agent."""
+    ensure_dirs()
+
+    if uninstall:
+        if platform.system() != "Darwin":
+            typer.echo("uninstalling a login agent is only wired up for macOS in v0.2", err=True)
+            raise typer.Exit(1)
+        removed = agent.uninstall()
+        typer.echo("removed LaunchAgent" if removed else "no LaunchAgent was installed")
+        return
+
+    typer.echo(f"config dir ready: {daemon_file().parent}")
+
+    system = platform.system()
+    if system == "Darwin":
+        try:
+            path = agent.install(sys.executable)
+        except RuntimeError as e:
+            typer.echo(f"error: {e}", err=True)
+            raise typer.Exit(1) from None
+        typer.echo(f"installed LaunchAgent at {path}")
+        typer.echo("daemon will start at login (and is running now).")
+    elif system == "Linux":
+        typer.echo("TODO: systemd user-unit install (Linux) lands in v0.2.1")
+    elif system == "Windows":
+        typer.echo("TODO: scheduled-task install (Windows) lands in v0.2.1")
+    else:
+        typer.echo(f"unsupported platform: {system}", err=True)
+        raise typer.Exit(1)
+
+
+@app.command()
+def restart() -> None:
+    """Restart the daemon to reload config and refresh the secret cache."""
+    if platform.system() == "Darwin" and agent.is_installed():
+        agent.restart()
+        typer.echo("kickstarted LaunchAgent daemon")
+        return
+    info = live_daemon_info()
+    if info is None:
+        typer.echo("no daemon is running")
+        return
+    try:
+        os.kill(info["pid"], signal.SIGTERM)
+        typer.echo("sent SIGTERM to ephemeral daemon; next 'keyward run' will start a fresh one")
+    except ProcessLookupError:
+        typer.echo("daemon not running")
+
+
+@app.command()
+def add(
+    name: str = typer.Argument(..., help="Short name for this key, e.g. openai."),
+    endpoint: str = typer.Option(..., "--endpoint", help="Allowlisted host, e.g. api.openai.com."),
+    env: list[str] = typer.Option(
+        None,
+        "--env",
+        help="Env var to set to the token (repeatable). Defaults to <NAME>_API_KEY.",
+    ),
+    base_url_env: str | None = typer.Option(
+        None,
+        "--base-url-env",
+        help="Env var for the base URL pointing at the daemon. Defaults to <NAME>_BASE_URL.",
+    ),
+    auth_style: str = typer.Option(
+        "bearer",
+        "--auth-style",
+        help="Upstream auth style: 'bearer' (OpenAI-style) or 'x-api-key' (Anthropic-style).",
+    ),
+) -> None:
+    """Store a secret in the OS keychain and mint a token for it."""
+    if auth_style not in store.AUTH_STYLES:
+        typer.echo(
+            f"error: --auth-style must be one of {store.AUTH_STYLES}, got {auth_style!r}",
+            err=True,
+        )
+        raise typer.Exit(2)
+    secret = typer.prompt("secret", hide_input=True)
+    env_vars = list(env) if env else [f"{name.upper()}_API_KEY"]
+    if base_url_env is None:
+        base_url_env = f"{name.upper()}_BASE_URL"
+    try:
+        entry = store.add_key(name, secret, endpoint, env_vars, base_url_env, auth_style)
+    except KeyError as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(1) from None
+    typer.echo(f"added '{entry.name}' -> {entry.endpoint} ({entry.auth_style})")
+    typer.echo(f"  token:    {entry.token}")
+    typer.echo(f"  env vars: {', '.join(entry.env_vars)}")
+    if entry.base_url_env:
+        typer.echo(f"  base url: {entry.base_url_env}")
+    _hint_restart_if_running()
+
+
+@app.command()
+def rotate(name: str) -> None:
+    """Replace the secret for an existing token. Token stays the same."""
+    secret = typer.prompt("new secret", hide_input=True)
+    entry = store.rotate_secret(name, secret)
+    if entry is None:
+        typer.echo(f"error: no key named '{name}'", err=True)
+        raise typer.Exit(1)
+    typer.echo(f"rotated secret for '{name}' (token unchanged: {entry.token})")
+    _hint_restart_if_running()
+
+
+@app.command("rm")
+def remove(
+    name: str,
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+) -> None:
+    """Delete a secret and revoke its token."""
+    if store.get_key(name) is None:
+        typer.echo(f"error: no key named '{name}'", err=True)
+        raise typer.Exit(1)
+    if not yes and not typer.confirm(f"remove '{name}' and delete its secret?"):
+        raise typer.Exit(0)
+    store.remove_key(name)
+    typer.echo(f"removed '{name}'")
+    _hint_restart_if_running()
+
+
+@app.command("list")
+def list_() -> None:
+    """Print registered keys, tokens, and endpoints."""
+    entries = store.list_keys()
+    if not entries:
+        typer.echo("(no keys registered; run 'keyward add <name> --endpoint <host>')")
+        return
+    width = max(len(e.name) for e in entries)
+    for e in entries:
+        style = f"[{e.auth_style}]" if e.auth_style != "bearer" else ""
+        typer.echo(f"{e.name.ljust(width)}  {e.token}  -> {e.endpoint} {style}".rstrip())
+
+
+@app.command()
+def approve(
+    name: str = typer.Argument(..., help="Key name."),
+    host: str = typer.Argument(..., help="Host to add to this key's allowlist."),
+) -> None:
+    """Add a new host to a key's allowlist. (Multi-endpoint support lands in v0.3.)"""
+    typer.echo(f"TODO: approve {host} for '{name}' (single-endpoint only in v0.2)")
+
+
+@app.command()
+def log(
+    since: str = typer.Option("1h", "--since", help="Time window, e.g. 10m, 2h, 1d."),
+    key: str | None = typer.Option(None, "--key", help="Filter to one key name."),
+) -> None:
+    """Tail the audit log."""
+    typer.echo(f"TODO: show audit log since={since} key={key}")
+
+
+def _wait_for_daemon(timeout: float = 2.0) -> dict | None:
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        if daemon_file().exists():
+            try:
+                return json.loads(daemon_file().read_text())
+            except json.JSONDecodeError:
+                pass
+        time.sleep(0.05)
+    return None
+
+
+@app.command(
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)
+def run(ctx: typer.Context) -> None:
+    """Run a command with daemon env vars injected.
+
+    Example: keyward run -- python app.py
+    """
+    argv = list(ctx.args)
+    if not argv:
+        typer.echo("error: provide a command after --, e.g. keyward run -- echo hi", err=True)
+        raise typer.Exit(2)
+
+    ensure_dirs()
+
+    info = live_daemon_info()
+    daemon_proc: subprocess.Popen | None = None
+    if info is None:
+        daemon_proc = subprocess.Popen([sys.executable, "-m", "keyward.daemon"])
+        info = _wait_for_daemon()
+        if info is None:
+            daemon_proc.terminate()
+            typer.echo("error: daemon did not start in time", err=True)
+            raise typer.Exit(1)
+
+    daemon_url = f"http://{info['host']}:{info['port']}"
+    env = {**os.environ, "KEYWARD_DAEMON": daemon_url}
+    for entry in store.list_keys():
+        for var in entry.env_vars:
+            env[var] = entry.token
+        if entry.base_url_env:
+            env[entry.base_url_env] = daemon_url
+
+    try:
+        exit_code = subprocess.run(argv, env=env).returncode
+    finally:
+        if daemon_proc is not None:
+            # This process started the daemon; clean it up. An existing long-running
+            # daemon (e.g. the LaunchAgent) is left alone.
+            with contextlib.suppress(ProcessLookupError):
+                os.kill(info["pid"], signal.SIGTERM)
+            try:
+                daemon_proc.wait(timeout=3.0)
+            except subprocess.TimeoutExpired:
+                daemon_proc.kill()
+                daemon_proc.wait(timeout=1.0)
+
+    raise typer.Exit(exit_code)
+
+
+if __name__ == "__main__":
+    app()

keyward/config.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def config_dir() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / "keyward"
+
+
+def state_dir() -> Path:
+    base = os.environ.get("XDG_STATE_HOME") or str(Path.home() / ".local" / "state")
+    return Path(base) / "keyward"
+
+
+def daemon_file() -> Path:
+    return config_dir() / "daemon.json"
+
+
+def audit_log() -> Path:
+    return state_dir() / "audit.log"
+
+
+def ensure_dirs() -> None:
+    config_dir().mkdir(parents=True, exist_ok=True)
+    state_dir().mkdir(parents=True, exist_ok=True)

keyward/daemon.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import signal
+import socket
+import sys
+from typing import NamedTuple
+
+from aiohttp import ClientError, ClientSession, web
+
+from keyward import store
+from keyward.config import daemon_file, ensure_dirs
+
+logger = logging.getLogger("keyward.daemon")
+
+
+class CacheEntry(NamedTuple):
+    name: str
+    endpoint: str
+    secret: str
+    auth_style: str
+
+
+CACHE_KEY: web.AppKey[dict[str, CacheEntry]] = web.AppKey("cache", dict[str, CacheEntry])
+CLIENT_KEY: web.AppKey[ClientSession] = web.AppKey("client", ClientSession)
+
+# Hop-by-hop headers (RFC 2616) plus auth headers we rewrite ourselves.
+# x-api-key is stripped so a client's fake token never reaches upstream.
+HOP_BY_HOP = {
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailers",
+    "transfer-encoding",
+    "upgrade",
+    "content-length",
+    "host",
+    "authorization",
+    "x-api-key",
+}
+
+
+def _extract_token(request: web.Request) -> str | None:
+    auth = request.headers.get("Authorization", "")
+    if auth.startswith("Bearer "):
+        candidate = auth[len("Bearer ") :].strip()
+        if candidate.startswith("kw_"):
+            return candidate
+    candidate = request.headers.get("x-api-key", "").strip()
+    if candidate.startswith("kw_"):
+        return candidate
+    return None
+
+
+async def handle(request: web.Request) -> web.StreamResponse:
+    token = _extract_token(request)
+    if token is None:
+        return web.Response(
+            status=401,
+            text="missing keyward token (expected Authorization: Bearer kw_... or x-api-key: kw_...)\n",
+        )
+
+    cache = request.app[CACHE_KEY]
+    entry = cache.get(token)
+    if entry is None:
+        return web.Response(status=403, text="unknown token\n")
+
+    base = entry.endpoint if "://" in entry.endpoint else f"https://{entry.endpoint}"
+    if not (base.startswith("https://") or base.startswith("http://")):
+        # Defense in depth: reject unexpected schemes even if config.toml was tampered with.
+        logger.error("rejecting non-http(s) endpoint for '%s'", entry.name)
+        return web.Response(status=502, text="invalid upstream scheme\n")
+    target_url = f"{base}{request.path_qs}"
+
+    out_headers = {k: v for k, v in request.headers.items() if k.lower() not in HOP_BY_HOP}
+    if entry.auth_style == "x-api-key":
+        out_headers["x-api-key"] = entry.secret
+    else:
+        out_headers["Authorization"] = f"Bearer {entry.secret}"
+
+    body = await request.read()
+
+    logger.info("%s %s -> %s [%s]", request.method, request.path, entry.endpoint, entry.name)
+
+    client = request.app[CLIENT_KEY]
+    try:
+        upstream_cm = client.request(
+            request.method,
+            target_url,
+            headers=out_headers,
+            data=body if body else None,
+            allow_redirects=False,
+        )
+    except ClientError as e:
+        logger.warning("upstream connect error: %s", e)
+        return web.Response(status=502, text=f"upstream error: {e}\n")
+
+    try:
+        async with upstream_cm as upstream:
+            resp_headers = {
+                k: v for k, v in upstream.headers.items() if k.lower() not in HOP_BY_HOP
+            }
+            resp = web.StreamResponse(status=upstream.status, headers=resp_headers)
+            await resp.prepare(request)
+            # iter_any yields as soon as bytes arrive; important for SSE streams.
+            async for chunk in upstream.content.iter_any():
+                await resp.write(chunk)
+            await resp.write_eof()
+            return resp
+    except ClientError as e:
+        logger.warning("upstream stream error: %s", e)
+        return web.Response(status=502, text=f"upstream error: {e}\n")
+
+
+def build_cache() -> dict[str, CacheEntry]:
+    cache: dict[str, CacheEntry] = {}
+    for entry in store.list_keys():
+        s = store.read_secret(entry.name)
+        if s is None:
+            logger.warning("no keychain entry for '%s'; skipping", entry.name)
+            continue
+        cache[entry.token] = CacheEntry(entry.name, entry.endpoint, s, entry.auth_style)
+    return cache
+
+
+def create_app(cache: dict[str, CacheEntry]) -> web.Application:
+    app = web.Application()
+    app[CACHE_KEY] = cache
+
+    async def _on_startup(app: web.Application) -> None:
+        app[CLIENT_KEY] = ClientSession()
+
+    async def _on_cleanup(app: web.Application) -> None:
+        await app[CLIENT_KEY].close()
+
+    app.on_startup.append(_on_startup)
+    app.on_cleanup.append(_on_cleanup)
+    app.router.add_route("*", "/{path:.*}", handle)
+    return app
+
+
+async def _run() -> None:
+    ensure_dirs()
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    sock.bind(("127.0.0.1", 0))
+    host, port = sock.getsockname()[:2]
+
+    cache = build_cache()
+    app = create_app(cache)
+
+    runner = web.AppRunner(app)
+    await runner.setup()
+    site = web.SockSite(runner, sock)
+    await site.start()
+
+    daemon_file().write_text(json.dumps({"host": host, "port": port, "pid": os.getpid()}))
+    logger.info("listening on %s:%d (%d keys cached)", host, port, len(cache))
+
+    stop = asyncio.Event()
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        loop.add_signal_handler(sig, stop.set)
+
+    try:
+        await stop.wait()
+    finally:
+        daemon_file().unlink(missing_ok=True)
+        await runner.cleanup()
+
+
+def main() -> None:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(name)s %(levelname)s %(message)s",
+    )
+    try:
+        asyncio.run(_run())
+    except KeyboardInterrupt:
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

keyward/discovery.py

@@ -0,0 +1,40 @@
+"""Daemon discovery: read daemon.json and check whether the registered process is alive."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+from keyward.config import daemon_file
+
+
+def live_daemon_info() -> dict[str, Any] | None:
+    """Return {host, port, pid} if a daemon is registered and its PID is alive, else None."""
+    path = daemon_file()
+    if not path.exists():
+        return None
+    try:
+        info = json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+    pid = info.get("pid")
+    if not isinstance(pid, int):
+        return None
+    try:
+        os.kill(pid, 0)
+    except (ProcessLookupError, PermissionError):
+        return None
+    return info
+
+
+def live_daemon_url() -> str | None:
+    """Return http://host:port for the live daemon, else None."""
+    info = live_daemon_info()
+    if info is None:
+        return None
+    host = info.get("host")
+    port = info.get("port")
+    if not host or not port:
+        return None
+    return f"http://{host}:{port}"

keyward/inject.py

@@ -0,0 +1,71 @@
+"""Runtime activation: rewrite env vars holding keyward tokens so SDKs talk to the daemon."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+from keyward.discovery import live_daemon_url
+from keyward.store import list_keys
+
+
+class DaemonNotRunning(RuntimeError):
+    """Raised by activate(strict=True) when no live keyward daemon is registered."""
+
+
+@dataclass
+class ActivateResult:
+    """Outcome of a keyward.activate() call.
+
+    Truthy when at least one key was activated, so existing ``if keyward.activate():``
+    checks keep working without modification.
+    """
+
+    activated: list[str] = field(default_factory=list)
+    """Keys whose base_url_env was rewritten to point at the daemon."""
+
+    skipped_no_env: list[str] = field(default_factory=list)
+    """Keys whose token was not found in any of their configured env_vars."""
+
+    skipped_no_base_url: list[str] = field(default_factory=list)
+    """Keys that have no base_url_env configured — nothing to rewrite."""
+
+    def __bool__(self) -> bool:
+        return bool(self.activated)
+
+
+def activate(*, strict: bool = True) -> ActivateResult:
+    """Point SDKs at the local keyward daemon for any env var holding a keyward token.
+
+    For each registered key, if any of its env_vars is set in os.environ to the
+    entry's token, set the entry's base_url_env to the daemon URL. Real keys
+    (values that don't match a registered token) and unset vars are left alone.
+
+    Returns an ActivateResult with three lists: activated, skipped_no_env,
+    skipped_no_base_url. The result is truthy when at least one key was activated.
+
+    With strict=True (default), raises DaemonNotRunning if no live daemon is
+    registered. With strict=False, returns an empty result and leaves env untouched.
+    """
+    url = live_daemon_url()
+    if url is None:
+        if strict:
+            raise DaemonNotRunning(
+                "keyward: no live daemon. Run 'keyward init' to install the login "
+                "agent, or wrap the process with 'keyward run'."
+            )
+        return ActivateResult()
+
+    result = ActivateResult()
+    for entry in list_keys():
+        if not entry.base_url_env:
+            result.skipped_no_base_url.append(entry.name)
+            continue
+        if not any(os.environ.get(var) == entry.token for var in entry.env_vars):
+            result.skipped_no_env.append(entry.name)
+            continue
+        os.environ[entry.base_url_env] = url
+        result.activated.append(entry.name)
+
+    os.environ.setdefault("KEYWARD_DAEMON", url)
+    return result

keyward/store.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import contextlib
+import datetime as dt
+import secrets
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import keyring
+import keyring.errors
+import tomli_w
+
+from keyward.config import config_dir, ensure_dirs
+
+KEYCHAIN_SERVICE = "keyward"
+
+
+def config_file() -> Path:
+    return config_dir() / "config.toml"
+
+
+AUTH_STYLES = ("bearer", "x-api-key")
+ALLOWED_SCHEMES = ("http", "https")
+
+
+def _validate_endpoint(endpoint: str) -> None:
+    if "://" in endpoint:
+        scheme = endpoint.split("://", 1)[0].lower()
+        if scheme not in ALLOWED_SCHEMES:
+            raise ValueError(f"endpoint scheme must be one of {ALLOWED_SCHEMES}, got {scheme!r}")
+
+
+@dataclass
+class KeyEntry:
+    name: str
+    token: str
+    endpoint: str
+    env_vars: list[str] = field(default_factory=list)
+    base_url_env: str | None = None
+    auth_style: str = "bearer"
+    created: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "token": self.token,
+            "endpoint": self.endpoint,
+            "env_vars": self.env_vars,
+            "auth_style": self.auth_style,
+            "created": self.created,
+        }
+        if self.base_url_env:
+            d["base_url_env"] = self.base_url_env
+        return d
+
+    @classmethod
+    def from_dict(cls, name: str, d: dict[str, Any]) -> KeyEntry:
+        return cls(
+            name=name,
+            token=d["token"],
+            endpoint=d["endpoint"],
+            env_vars=list(d.get("env_vars", [])),
+            base_url_env=d.get("base_url_env"),
+            # default to bearer for configs written before auth_style existed
+            auth_style=d.get("auth_style", "bearer"),
+            created=d.get("created", ""),
+        )
+
+
+def mint_token() -> str:
+    return "kw_" + secrets.token_hex(8)
+
+
+def _load_raw() -> dict[str, Any]:
+    path = config_file()
+    if not path.exists():
+        return {}
+    with path.open("rb") as f:
+        return tomllib.load(f)
+
+
+def _save_raw(data: dict[str, Any]) -> None:
+    ensure_dirs()
+    with config_file().open("wb") as f:
+        tomli_w.dump(data, f)
+
+
+def list_keys() -> list[KeyEntry]:
+    data = _load_raw()
+    return [KeyEntry.from_dict(n, d) for n, d in data.get("keys", {}).items()]
+
+
+def get_key(name: str) -> KeyEntry | None:
+    data = _load_raw()
+    d = data.get("keys", {}).get(name)
+    return KeyEntry.from_dict(name, d) if d else None
+
+
+def get_key_by_token(token: str) -> KeyEntry | None:
+    for k in list_keys():
+        if k.token == token:
+            return k
+    return None
+
+
+def add_key(
+    name: str,
+    secret: str,
+    endpoint: str,
+    env_vars: list[str],
+    base_url_env: str | None,
+    auth_style: str = "bearer",
+) -> KeyEntry:
+    if auth_style not in AUTH_STYLES:
+        raise ValueError(f"auth_style must be one of {AUTH_STYLES}, got {auth_style!r}")
+    _validate_endpoint(endpoint)
+    if get_key(name) is not None:
+        raise KeyError(f"key '{name}' already exists; use 'keyward rotate' to change its secret")
+    keyring.set_password(KEYCHAIN_SERVICE, name, secret)
+    entry = KeyEntry(
+        name=name,
+        token=mint_token(),
+        endpoint=endpoint,
+        env_vars=env_vars,
+        base_url_env=base_url_env,
+        auth_style=auth_style,
+        created=dt.datetime.now(dt.UTC).isoformat(timespec="seconds"),
+    )
+    data = _load_raw()
+    data.setdefault("keys", {})[name] = entry.to_dict()
+    _save_raw(data)
+    return entry
+
+
+def remove_key(name: str) -> bool:
+    data = _load_raw()
+    keys = data.get("keys", {})
+    if name not in keys:
+        return False
+    del keys[name]
+    _save_raw(data)
+    with contextlib.suppress(keyring.errors.PasswordDeleteError):
+        keyring.delete_password(KEYCHAIN_SERVICE, name)
+    return True
+
+
+def rotate_secret(name: str, new_secret: str) -> KeyEntry | None:
+    entry = get_key(name)
+    if entry is None:
+        return None
+    keyring.set_password(KEYCHAIN_SERVICE, name, new_secret)
+    return entry
+
+
+def read_secret(name: str) -> str | None:
+    return keyring.get_password(KEYCHAIN_SERVICE, name)

keyward-0.0.1.dist-info/METADATA

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: keyward
+Version: 0.0.1
+Summary: Local secret broker that keeps API keys out of files AI agents can read.
+Project-URL: Homepage, https://github.com/sumedhrasal/keyward
+Project-URL: Repository, https://github.com/sumedhrasal/keyward
+Author: sumedh
+License: MIT License
+        
+        Copyright (c) 2026 sumedh
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ai-agents,api-keys,proxy,secrets,security
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: keyring>=24.0
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# keyward
+
+A local secret broker for developers who run AI coding agents on their own machines.
+
+## The goal
+
+Keep API keys out of any file an AI agent, co-pilot, or third-party tool can read,
+without adding friction to normal development.
+
+Your code never contains real keys. It contains opaque tokens like `kw_ab12cd34`.
+A local daemon swaps the token for the real key only when the outbound request
+goes to an allowlisted endpoint, and records every use.
+
+If an agent reads your code, config, or environment, it sees tokens. Tokens are
+useless off-host: they only resolve inside the daemon, which will not forward
+them to destinations you have not explicitly approved.
+
+## Why this is not just encryption
+
+"One-way encryption you can decrypt" does not exist. What this package actually
+provides is **tokenization plus a scoped, audited forward proxy**. The security
+properties that matter are:
+
+- real secrets live in the OS keychain, never on disk in plaintext
+- code and config contain only tokens
+- the daemon forwards to an allowlist, so a leaked token cannot exfiltrate data to a new host
+- every resolution is logged
+- new destinations require explicit user approval
+
+## Intended user experience
+
+Onboarding is the product. If any step feels heavier than `export KEY=...`,
+it has failed its design goal.
+
+```
+# one-time setup
+pip install keyward
+keyward init
+
+# add a key (prompts for the secret; never passed on the command line)
+keyward add openai --endpoint api.openai.com
+
+# run any program with tokens injected as env vars
+keyward run -- python app.py
+keyward run -- pytest
+keyward run -- npm start
+
+# rotate a key in place; tokens stay the same so no code changes
+keyward rotate openai
+
+# list, remove, inspect
+keyward list
+keyward rm openai
+keyward log --since 1h
+```
+
+Your code stays boring:
+
+```python
+import os, openai
+client = openai.OpenAI()   # reads OPENAI_API_KEY and OPENAI_BASE_URL from env
+```
+
+Under `keyward run`, those variables point at the local daemon with a token.
+Outside `keyward run`, they are not set at all.
+
+## Activating from inside your app
+
+If you don't want to wrap every command with `keyward run`, call
+`keyward.activate()` once near the top of your app. With the daemon installed
+as a login agent (`keyward init`), this is all you need:
+
+```python
+# .env (or your normal env-loading mechanism)
+# OPENAI_API_KEY=kw_ab12cd34
+import os
+from dotenv import load_dotenv
+load_dotenv()
+
+import keyward
+keyward.activate()       # rewrites OPENAI_BASE_URL to point at the daemon
+
+from openai import OpenAI
+client = OpenAI()        # transparently goes through keyward
+```
+
+`activate()` looks at every registered key, and for each one whose `env_vars`
+already hold its token in `os.environ`, sets the matching `base_url_env` to the
+daemon URL. Real keys are left alone. It also exports `KEYWARD_DAEMON` as a
+stable signal you can check from your code (`if "KEYWARD_DAEMON" in os.environ:
+...`) to confirm activation.
+
+It returns a `keyward.ActivateResult` with three lists so you can see exactly
+what happened:
+
+```python
+result = keyward.activate(strict=False)
+if result.skipped_no_env:
+    print(f"token not found in env for: {result.skipped_no_env}")
+    print("Did you load your .env file before calling activate()?")
+# result.activated       — keys that are now routing through the daemon
+# result.skipped_no_env  — keys whose token was not found in any env var
+# result.skipped_no_base_url — keys with no base_url_env configured
+```
+
+If no daemon is running, `activate()` raises `keyward.DaemonNotRunning`. Pass
+`strict=False` to return an empty result instead — useful for code that should
+work both with and without keyward installed.
+
+## What works today (v0.2)
+
+| Area                  | Status                                                                 |
+|-----------------------|------------------------------------------------------------------------|
+| CLI commands          | `init`, `add`, `list`, `rm`, `rotate`, `restart`, `run` all functional |
+| Keychain storage      | macOS Keychain, Windows Credential Manager, Linux libsecret via `keyring` |
+| Proxy forwarding      | Authorization: Bearer and x-api-key, on both ingress and egress        |
+| Streaming             | Server-Sent Events forwarded without buffering                         |
+| Login agent           | macOS LaunchAgent install/uninstall/kickstart via `keyward init`       |
+| Daemon reuse          | `keyward run` reuses a live daemon; else spawns ephemeral              |
+| Audit log             | Stub only (prints TODO; no log is written yet)                         |
+| Endpoint enforcement  | Each token is bound to one host at `keyward add` time; the daemon ignores the request host and always forwards to the stored endpoint — so a token cannot be used against a different host |
+| Multi-endpoint allowlist + approval flow | Not yet — v0.3 scope; see ARCHITECTURE.md   |
+| Linux systemd / Windows scheduled task | Not wired up yet                                      |
+| Websocket proxying    | Returns 501; HTTP only for now                                         |
+| Request body streaming| Buffered; fine for LLM chat, not for large uploads                     |
+| Caller attestation    | Trust-anything on localhost; see ARCHITECTURE.md                       |
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full design, threat
+model, and the list of deferred items.
+
+## Verifying the key swap
+
+The sharpest test is to point keyward at a request-echoing endpoint and look
+for your raw secret (and the absence of the token) in the response.
+
+```bash
+# pick a distinctive fake secret so you can spot it in the echo
+keyward add echotest --endpoint httpbin.org
+# at the prompt, enter: sk-fake-secret-12345
+
+keyward restart   # only needed if a LaunchAgent daemon is already running
+
+keyward run -- curl -s "$ECHOTEST_BASE_URL/anything" \
+    -H "Authorization: Bearer $ECHOTEST_API_KEY"
+```
+
+In the JSON response, under `headers.Authorization`:
+- `Bearer sk-fake-secret-12345` means the swap worked.
+- Anything starting with `Bearer kw_` means the swap did not happen (bug).
+
+For the Anthropic-style (x-api-key):
+
+```bash
+keyward add echotestx --endpoint httpbin.org --auth-style x-api-key
+keyward restart
+keyward run -- curl -s "$ECHOTESTX_BASE_URL/anything" \
+    -H "x-api-key: $ECHOTESTX_API_KEY"
+```
+
+Check `headers.X-Api-Key` in the response.
+
+Clean up with `keyward rm echotest -y && keyward rm echotestx -y`.
+
+There is also a Python equivalent that uses `keyward.activate()`:
+
+```bash
+keyward add echotest --endpoint httpbin.org
+keyward restart
+uv run python scripts/verify_swap.py echotest
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

keyward-0.0.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+keyward/__init__.py,sha256=c-Ho30xFe6WSf6otERWOV40Kg1ke_11yrQW0nQk8b2Q,250
+keyward/__main__.py,sha256=rfe4NvMNbr529NYVRRzK7zla8KyTJnGX9yKq-fnhb1Q,66
+keyward/agent.py,sha256=BF7I1-mXAGuaLOZhkUYbE5YXEaIytMIdDiY-qkDcHUs,2508
+keyward/cli.py,sha256=Q1uahOxzFbpGw8Z-Vz-FnIOHfI2FVlj0t662Ior-qAA,8828
+keyward/config.py,sha256=ng0FCwvs5elCI-IG7sVH7zDbyC8u1KYjKTNTo7ddEs8,621
+keyward/daemon.py,sha256=nw7pJ16MBU3uHvPg22Pw1qNZWYFshOudTSwOTBG_IpA,5786
+keyward/discovery.py,sha256=qOrBEQiOPq1R72E3T-gO2I5JrNxzoekehjBYeSVHOQs,1061
+keyward/inject.py,sha256=TUKhHOxz3ZSnZGqs33pc8fEBotfr7zgJNPz5WqfK4-8,2589
+keyward/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+keyward/store.py,sha256=dY2majUn6SgvFm3O0V32sJwOZCLt-gDYQ5K2UMwLiio,4152
+keyward-0.0.1.dist-info/METADATA,sha256=thmGi-3RsiCcTfzMQuOafHhEt6dZGV7m5KyYjTzD3OI,8958
+keyward-0.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+keyward-0.0.1.dist-info/entry_points.txt,sha256=JM_NpweffKRbcGU8oQuSuPTnnmoxhyokKTfmKS2mXlw,44
+keyward-0.0.1.dist-info/licenses/LICENSE,sha256=SKD37zOb0Yc0gnPgr3IhnIu3cJMeer2FBrjDc9IwTWI,1063
+keyward-0.0.1.dist-info/RECORD,,

keyward-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

keyward-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+keyward = keyward.cli:app

keyward-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sumedh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.