akprx 0.1.0__tar.gz

akprx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexey Floppa
+
+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.

akprx-0.1.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: akprx
+Version: 0.1.0
+Summary: Agent Key Proxy — credential broker daemon for AI agents on Linux
+Author-email: Alexey Floppa <you@example.com>
+License: MIT License
+        
+        Copyright (c) 2026 Alexey Floppa
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/belka0fficial/akprx
+Project-URL: Repository, https://github.com/belka0fficial/akprx
+Project-URL: Issues, https://github.com/belka0fficial/akprx/issues
+Project-URL: Changelog, https://github.com/belka0fficial/akprx/blob/main/CHANGELOG.md
+Keywords: ai-agent,api-proxy,credentials,secrets,broker,daemon,linux
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: No Input/Output (Daemon)
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn>=0.29.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Dynamic: license-file
+
+# akprx
+
+**Agent Key Proxy** — credential broker daemon for AI agents on Linux.
+
+Your agent needs to call external APIs. You don't want it holding the keys.  
+`akprx` sits in the middle: the agent asks it to make calls, it injects the credentials, returns only the result. The agent never sees a token.
+
+```
+agent → POST /call → akprx injects key → GitHub API
+                  ↑
+         key never crosses this boundary
+```
+
+---
+
+## The problem
+
+When an AI agent has direct access to API keys:
+
+- Keys live in env vars or config files the agent can read
+- A prompt injection attack can extract them
+- A compromised plugin leaks every credential the agent holds
+- You have no visibility into what the agent calls or with what
+
+## The solution
+
+`akprx` runs as a systemd daemon on `127.0.0.1` only — unreachable from outside the machine. The agent user can talk to it over HTTP. It cannot read the secret files. It cannot read the environment of the broker process. It gets results, never credentials.
+
+---
+
+## Install
+
+```bash
+pip install akprx
+sudo akprx setup
+```
+
+That's it. `setup` creates the system user, directories, permissions, and the systemd service. Nothing else to configure.
+
+---
+
+## Quickstart
+
+```bash
+# check everything is running
+akprx status
+
+# store an API key (value is hidden input)
+akprx key add GITHUB_TOKEN
+
+# register a provider
+akprx adaptor add
+
+# make a call through the proxy
+akprx call github /repos/youruser/yourrepo
+
+# POST with a body
+akprx call github /repos/youruser/yourrepo/issues \
+  --method POST \
+  --data '{"title": "bug report", "body": "details here"}'
+```
+
+---
+
+## Commands
+
+```
+akprx status                      service health, keys, adaptors
+
+akprx adaptor list                list registered adaptors
+akprx adaptor add                 register a new adaptor (interactive)
+akprx adaptor show <name>         show full config of one adaptor
+akprx adaptor remove <name>       remove an adaptor
+
+akprx key list                    list stored key names (no values shown)
+akprx key add <name>              store a new key (value prompted, hidden)
+akprx key remove <name>           remove a key
+akprx key rotate <name>           replace a key value (prompted, hidden)
+
+akprx call <adaptor> <path>       GET request through adaptor
+akprx call <adaptor> <path> --method POST --data '{...}'
+
+akprx setup                       first-time setup (run with sudo)
+akprx version                     print version
+```
+
+---
+
+## How adaptors work
+
+An adaptor is a registered API provider. It stores:
+
+- `base_url` — the root URL of the API
+- `secret_env` — which env var holds the token
+- `auth_header` / `auth_prefix` — how to inject the credential
+- `extra_headers` — any static headers the API requires
+
+Once registered, the agent can call any endpoint on that provider freely.  
+To add a new provider, run `akprx adaptor add` and answer the prompts.
+
+### Example — GitHub
+
+```bash
+akprx adaptor add
+# name:              github
+# base url:          https://api.github.com
+# secret env var:    GITHUB_TOKEN
+# auth header:       Authorization
+# auth prefix:       Bearer
+# extra headers:
+#   Accept:          application/vnd.github+json
+#   X-GitHub-Api-Version: 2022-11-28
+```
+
+---
+
+## File layout
+
+```
+/srv/akprx/
+├── adaptors.json        registered providers   owner: akprx:akprx 600
+└── secrets/
+    └── secrets.env      API keys               owner: akprx:akprx 600
+```
+
+The `akprx` system user owns all files.  
+The agent user cannot read either file.  
+Root can manage everything via sudo.
+
+---
+
+## Security model
+
+| What                        | Who can access             |
+|-----------------------------|----------------------------|
+| `secrets.env`               | `akprx` user only          |
+| `adaptors.json`             | `akprx` user only          |
+| broker HTTP API             | any local process          |
+| secret values via HTTP API  | nobody — never returned    |
+| key names via HTTP API      | any local process          |
+| port 8080 from outside VPS  | nobody — loopback only     |
+
+The security guarantee is structural — enforced by Linux file permissions and network binding, not application-level checks.
+
+---
+
+## Who this is for
+
+- Running a self-hosted AI agent (OpenClaw, Claude Code, or similar) on a Linux VPS
+- Want the agent to call external APIs on your behalf
+- Don't want the agent to hold or see raw credentials
+- Want a simple CLI to manage everything without editing config files
+
+## Who this is NOT for
+
+- Enterprise teams needing secret rotation, SSO, or audit compliance → use HashiCorp Vault
+- Cloud-native setups → use AWS Secrets Manager
+- Docker-only workflows → use OneCLI
+- Multi-user access control → out of scope
+
+---
+
+## Requirements
+
+- Linux (systemd-based)
+- Python 3.10+
+- Root access for initial setup
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+---
+
+## Author
+
+[Alexey Floppa](https://github.com/belka0fficial)

akprx-0.1.0/README.md

@@ -0,0 +1,179 @@
+# akprx
+
+**Agent Key Proxy** — credential broker daemon for AI agents on Linux.
+
+Your agent needs to call external APIs. You don't want it holding the keys.  
+`akprx` sits in the middle: the agent asks it to make calls, it injects the credentials, returns only the result. The agent never sees a token.
+
+```
+agent → POST /call → akprx injects key → GitHub API
+                  ↑
+         key never crosses this boundary
+```
+
+---
+
+## The problem
+
+When an AI agent has direct access to API keys:
+
+- Keys live in env vars or config files the agent can read
+- A prompt injection attack can extract them
+- A compromised plugin leaks every credential the agent holds
+- You have no visibility into what the agent calls or with what
+
+## The solution
+
+`akprx` runs as a systemd daemon on `127.0.0.1` only — unreachable from outside the machine. The agent user can talk to it over HTTP. It cannot read the secret files. It cannot read the environment of the broker process. It gets results, never credentials.
+
+---
+
+## Install
+
+```bash
+pip install akprx
+sudo akprx setup
+```
+
+That's it. `setup` creates the system user, directories, permissions, and the systemd service. Nothing else to configure.
+
+---
+
+## Quickstart
+
+```bash
+# check everything is running
+akprx status
+
+# store an API key (value is hidden input)
+akprx key add GITHUB_TOKEN
+
+# register a provider
+akprx adaptor add
+
+# make a call through the proxy
+akprx call github /repos/youruser/yourrepo
+
+# POST with a body
+akprx call github /repos/youruser/yourrepo/issues \
+  --method POST \
+  --data '{"title": "bug report", "body": "details here"}'
+```
+
+---
+
+## Commands
+
+```
+akprx status                      service health, keys, adaptors
+
+akprx adaptor list                list registered adaptors
+akprx adaptor add                 register a new adaptor (interactive)
+akprx adaptor show <name>         show full config of one adaptor
+akprx adaptor remove <name>       remove an adaptor
+
+akprx key list                    list stored key names (no values shown)
+akprx key add <name>              store a new key (value prompted, hidden)
+akprx key remove <name>           remove a key
+akprx key rotate <name>           replace a key value (prompted, hidden)
+
+akprx call <adaptor> <path>       GET request through adaptor
+akprx call <adaptor> <path> --method POST --data '{...}'
+
+akprx setup                       first-time setup (run with sudo)
+akprx version                     print version
+```
+
+---
+
+## How adaptors work
+
+An adaptor is a registered API provider. It stores:
+
+- `base_url` — the root URL of the API
+- `secret_env` — which env var holds the token
+- `auth_header` / `auth_prefix` — how to inject the credential
+- `extra_headers` — any static headers the API requires
+
+Once registered, the agent can call any endpoint on that provider freely.  
+To add a new provider, run `akprx adaptor add` and answer the prompts.
+
+### Example — GitHub
+
+```bash
+akprx adaptor add
+# name:              github
+# base url:          https://api.github.com
+# secret env var:    GITHUB_TOKEN
+# auth header:       Authorization
+# auth prefix:       Bearer
+# extra headers:
+#   Accept:          application/vnd.github+json
+#   X-GitHub-Api-Version: 2022-11-28
+```
+
+---
+
+## File layout
+
+```
+/srv/akprx/
+├── adaptors.json        registered providers   owner: akprx:akprx 600
+└── secrets/
+    └── secrets.env      API keys               owner: akprx:akprx 600
+```
+
+The `akprx` system user owns all files.  
+The agent user cannot read either file.  
+Root can manage everything via sudo.
+
+---
+
+## Security model
+
+| What                        | Who can access             |
+|-----------------------------|----------------------------|
+| `secrets.env`               | `akprx` user only          |
+| `adaptors.json`             | `akprx` user only          |
+| broker HTTP API             | any local process          |
+| secret values via HTTP API  | nobody — never returned    |
+| key names via HTTP API      | any local process          |
+| port 8080 from outside VPS  | nobody — loopback only     |
+
+The security guarantee is structural — enforced by Linux file permissions and network binding, not application-level checks.
+
+---
+
+## Who this is for
+
+- Running a self-hosted AI agent (OpenClaw, Claude Code, or similar) on a Linux VPS
+- Want the agent to call external APIs on your behalf
+- Don't want the agent to hold or see raw credentials
+- Want a simple CLI to manage everything without editing config files
+
+## Who this is NOT for
+
+- Enterprise teams needing secret rotation, SSO, or audit compliance → use HashiCorp Vault
+- Cloud-native setups → use AWS Secrets Manager
+- Docker-only workflows → use OneCLI
+- Multi-user access control → out of scope
+
+---
+
+## Requirements
+
+- Linux (systemd-based)
+- Python 3.10+
+- Root access for initial setup
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+---
+
+## Author
+
+[Alexey Floppa](https://github.com/belka0fficial)

akprx-0.1.0/akprx/__init__.py

@@ -0,0 +1,7 @@
+"""
+akprx — Agent Key Proxy
+Credential broker daemon for AI agents on Linux.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Alexey Floppa"

akprx-0.1.0/akprx/cli/adaptor.py

@@ -0,0 +1,96 @@
+"""
+akprx.cli.adaptor
+Subcommands for managing adaptors.
+"""
+
+import sys
+
+from akprx.cli import http
+
+USAGE = """\
+usage:
+  akprx adaptor list
+  akprx adaptor add
+  akprx adaptor show <name>
+  akprx adaptor remove <name>
+"""
+
+
+def _list() -> None:
+    data = http.get("/adaptors")
+    if data["total"] == 0:
+        print("no adaptors registered.")
+        print("add one: akprx adaptor add")
+        return
+    for a in data["adaptors"]:
+        sym = "✓" if a["status"] == "ok" else "✗"
+        name = a["name"].ljust(16)
+        url = a["config"]["base_url"].ljust(40)
+        state = "ok" if a["config"]["secret_loaded"] else "MISSING SECRET"
+        print(f"  {sym} {name} {url} {state}")
+        for issue in a.get("issues", []):
+            print(f"    ! {issue}")
+
+
+def _show(name: str) -> None:
+    http.pp(http.get(f"/adaptors/{name}"))
+
+
+def _add() -> None:
+    print("register a new adaptor.\n")
+    name        = input("  name (e.g. github):              ").strip()
+    base_url    = input("  base url:                        ").strip()
+    secret_env  = input("  secret env var name:             ").strip()
+    auth_header = input("  auth header [Authorization]:     ").strip() or "Authorization"
+    auth_prefix = input("  auth prefix [Bearer]:            ").strip() or "Bearer"
+
+    extra: dict[str, str] = {}
+    print("  extra headers (blank name to finish):")
+    while True:
+        k = input("    header name:  ").strip()
+        if not k:
+            break
+        v = input("    header value: ").strip()
+        extra[k] = v
+
+    result = http.post("/adaptors", {
+        "name": name,
+        "base_url": base_url,
+        "secret_env": secret_env,
+        "auth_header": auth_header,
+        "auth_prefix": auth_prefix,
+        "extra_headers": extra,
+    })
+    http.pp(result)
+
+
+def _remove(name: str) -> None:
+    result = http.delete(f"/adaptors/{name}")
+    http.pp(result)
+
+
+def run(args: list[str]) -> None:
+    if not args or args[0] in ("-h", "--help", "help"):
+        print(USAGE)
+        sys.exit(0)
+
+    sub = args[0]
+
+    if sub == "list":
+        _list()
+    elif sub == "add":
+        _add()
+    elif sub == "show":
+        if len(args) < 2:
+            print("usage: akprx adaptor show <name>", file=sys.stderr)
+            sys.exit(1)
+        _show(args[1])
+    elif sub == "remove":
+        if len(args) < 2:
+            print("usage: akprx adaptor remove <name>", file=sys.stderr)
+            sys.exit(1)
+        _remove(args[1])
+    else:
+        print(f"akprx adaptor: unknown subcommand '{sub}'", file=sys.stderr)
+        print(USAGE, file=sys.stderr)
+        sys.exit(1)

akprx-0.1.0/akprx/cli/call.py

@@ -0,0 +1,61 @@
+"""
+akprx.cli.call
+Fire an authenticated API call through a registered adaptor.
+"""
+
+import json
+import sys
+
+from akprx.cli import http
+
+USAGE = """\
+usage:
+  akprx call <adaptor> <path>
+  akprx call <adaptor> <path> --method POST --data '{...}'
+
+examples:
+  akprx call github /repos/belka0fficial/belka.life
+  akprx call github /repos/belka0fficial/belka.life/issues --method POST --data '{"title":"bug"}'
+"""
+
+
+def run(args: list[str]) -> None:
+    if not args or args[0] in ("-h", "--help", "help"):
+        print(USAGE)
+        sys.exit(0)
+
+    if len(args) < 2:
+        print("usage: akprx call <adaptor> <path>", file=sys.stderr)
+        sys.exit(1)
+
+    adaptor = args[0]
+    path    = args[1]
+    method  = "GET"
+    data    = None
+
+    i = 2
+    while i < len(args):
+        if args[i] == "--method" and i + 1 < len(args):
+            method = args[i + 1].upper()
+            i += 2
+        elif args[i] == "--data" and i + 1 < len(args):
+            data = args[i + 1]
+            i += 2
+        else:
+            i += 1
+
+    body: dict = {
+        "adaptor": adaptor,
+        "method": method,
+        "path": path,
+    }
+
+    if data:
+        try:
+            body["payload"] = json.loads(data)
+        except json.JSONDecodeError:
+            print("error: --data is not valid JSON", file=sys.stderr)
+            sys.exit(1)
+
+    result = http.post("/call", body)
+    http.pp(result)

akprx-0.1.0/akprx/cli/http.py

@@ -0,0 +1,57 @@
+"""
+akprx.cli.http
+Shared HTTP client for CLI commands.
+All requests go to the local broker.
+"""
+
+import json
+import sys
+import urllib.error
+import urllib.request
+
+from akprx.config import BASE_URL
+
+
+def request(method: str, path: str, body: dict | None = None) -> dict:
+    url = BASE_URL + path
+    data = json.dumps(body).encode() if body is not None else None
+    headers = {"Content-Type": "application/json"} if data else {}
+    req = urllib.request.Request(url, data=data, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(req) as resp:
+            return json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        raw = e.read().decode()
+        try:
+            detail = json.loads(raw).get("detail", raw)
+        except Exception:
+            detail = raw
+        print(f"error {e.code}: {detail}", file=sys.stderr)
+        sys.exit(1)
+    except urllib.error.URLError:
+        print(
+            f"error: cannot reach akprx at {BASE_URL}\n"
+            "       is the service running? try: systemctl status akprx",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+def get(path: str) -> dict:
+    return request("GET", path)
+
+
+def post(path: str, body: dict) -> dict:
+    return request("POST", path, body)
+
+
+def put(path: str, body: dict) -> dict:
+    return request("PUT", path, body)
+
+
+def delete(path: str) -> dict:
+    return request("DELETE", path)
+
+
+def pp(data: dict) -> None:
+    print(json.dumps(data, indent=2))