skeyd 0.2.0__py3-none-any.whl

skeyd/__init__.py

@@ -0,0 +1,69 @@
+# skeyd — a Zero-Trust secrets broker for AI agents and automation.
+#
+# * skeyd stores credentials encrypted at rest and hands them to child processes under an explicit policy, instead of letting a program read them back.  The difference matters for agent workloads: an agent that can *use* a credential without ever *holding* one cannot leak it into a context window, a transcript, or a bug report.
+#
+# Typical library use::
+#
+#     from skeyd import AccessRequest, PolicyEngine, load_policy
+#
+#     engine = PolicyEngine(load_policy(Path("policy.toml")))
+#     decision = engine.evaluate(AccessRequest(label="OPENAI_API_KEY", argv=("python3", "job.py")))
+#     if decision.allowed:
+#         ...
+#
+# The CLI is the primary interface; see ``skeyd --help`` or the README.
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+__all__ = [
+    "AccessRequest",
+    "AuditEvent",
+    "AuditLog",
+    "Decision",
+    "EncryptedFileStore",
+    "ExitCode",
+    "Policy",
+    "PolicyEngine",
+    "Redactor",
+    "SecretValue",
+    "SkeydError",
+    "__version__",
+    "load_policy",
+    "resolve_paths",
+]
+
+
+def __getattr__(name: str) -> object:
+    # Resolve public names lazily.
+    #
+    # Importing ``skeyd`` should not pull in the cryptography backend, the policy parser and the subprocess machinery just so a caller can read ``__version__`` — which is exactly what packaging tools and ``--version`` do most often.
+    if name in {"AccessRequest", "Decision", "Policy", "PolicyEngine", "load_policy"}:
+        from . import policy
+
+        return getattr(policy, name)
+    if name in {"AuditEvent", "AuditLog"}:
+        from . import audit
+
+        return getattr(audit, name)
+    if name == "EncryptedFileStore":
+        from .store import EncryptedFileStore
+
+        return EncryptedFileStore
+    if name in {"ExitCode", "SkeydError"}:
+        from . import errors
+
+        return getattr(errors, name)
+    if name == "Redactor":
+        from .redaction import Redactor
+
+        return Redactor
+    if name == "SecretValue":
+        from .secretvalue import SecretValue
+
+        return SecretValue
+    if name == "resolve_paths":
+        from .paths import resolve_paths
+
+        return resolve_paths
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

skeyd/__main__.py

@@ -0,0 +1,10 @@
+# Allow ``python -m skeyd`` as an alternative to the console script.
+
+from __future__ import annotations
+
+import sys
+
+from .cli.main import main
+
+if __name__ == "__main__":
+    sys.exit(main())

skeyd/agent.py

@@ -0,0 +1,248 @@
+# The machine-readable interface for AI agents.
+#
+# An agent integrates with skeyd the same way it integrates with any other tool: it asks for a manifest of callable tools with JSON Schema inputs, then calls them by name.  ``skeyd agent manifest`` emits that manifest in whichever dialect the calling framework expects, and ``skeyd agent call`` executes one tool and returns a JSON envelope.
+#
+# * **There is deliberately no ``get_secret`` tool.**
+#
+# That absence is the whole design.  A tool that returns plaintext would put the credential into the model's context window, where it is copied into transcripts, evaluation datasets, error reports and — for hosted models — a third party's infrastructure.  skeyd's agent surface lets an agent *use* a credential (by running a command with it injected) and *reason about* credentials (names, metadata, what policy permits) without ever holding one.
+#
+# Every tool here delegates to the same functions the CLI uses, so the two surfaces cannot drift apart: an authorization check that applies to ``skeyd run`` applies identically to ``skeyd_run``.
+
+from __future__ import annotations
+
+from typing import Any, Final
+
+__all__ = [
+    "AGENT_SCHEMA_VERSION",
+    "TOOLS",
+    "ManifestFormat",
+    "build_manifest",
+    "tool_names",
+]
+
+#: Version of the agent contract: tool names, input schemas and envelope shape.
+#: Bumped only on a breaking change, so an integration can assert at startup.
+AGENT_SCHEMA_VERSION: Final = 1
+
+ManifestFormat = str  # "native" | "anthropic" | "openai" | "mcp"
+
+_LABEL = {
+    "type": "string",
+    "description": "The label the credential is stored under, e.g. 'OPENAI_API_KEY'.",
+}
+
+_COMMAND = {
+    "type": "array",
+    "items": {"type": "string"},
+    "minItems": 1,
+    "description": (
+        "The command to run, as an argv array (not a shell string). "
+        'Example: ["python3", "jobs/summarise.py", "--input", "data.json"].'
+    ),
+}
+
+_PURPOSE = {
+    "type": "string",
+    "description": (
+        "Short human-readable reason for this access, recorded in the audit log. "
+        "Some policies require it."
+    ),
+}
+
+
+TOOLS: Final[tuple[dict[str, Any], ...]] = (
+    {
+        "name": "skeyd_list_secrets",
+        "description": (
+            "List the credential labels available in the store, with metadata: how many "
+            "values each holds, which environment variable it maps to, whether any have "
+            "expired, and whether a policy rule permits using it. Never returns secret "
+            "values — skeyd is a broker, not a vault you can read from."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "skeyd_check_access",
+        "description": (
+            "Ask whether a given command would be permitted to use a given credential, "
+            "without running anything and without decrypting the store. Use this before "
+            "skeyd_run to find out what you are allowed to do, and to get a precise "
+            "explanation when something is forbidden."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "label": _LABEL,
+                "command": _COMMAND,
+                "purpose": _PURPOSE,
+                "cwd": {
+                    "type": "string",
+                    "description": "Working directory the command would run in.",
+                },
+            },
+            "required": ["label", "command"],
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "skeyd_run",
+        "description": (
+            "Run a command with one credential injected into its environment. The "
+            "credential is never returned to you and never appears on the command line. "
+            "Output is scrubbed of the credential before you see it. Returns the exit "
+            "code, duration, and (when capture is enabled) the redacted stdout/stderr. "
+            "Denied requests return ok=false with a policy explanation."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "label": _LABEL,
+                "command": _COMMAND,
+                "purpose": _PURPOSE,
+                "timeout": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "description": (
+                        "Wall-clock limit in seconds. If this exceeds the ceiling the "
+                        "matching policy rule allows, the request is denied outright "
+                        "(not silently capped) — omit this to use the rule's own ceiling."
+                    ),
+                },
+                "cwd": {
+                    "type": "string",
+                    "description": "Working directory for the command.",
+                },
+                "capture_output": {
+                    "type": "boolean",
+                    "description": (
+                        "Return the command's redacted stdout/stderr in the response. "
+                        "Defaults to the policy setting."
+                    ),
+                },
+            },
+            "required": ["label", "command"],
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "skeyd_describe_policy",
+        "description": (
+            "Describe the rules that govern credential use — optionally narrowed to one "
+            "label. Use this to understand the boundaries you are operating within before "
+            "proposing a plan that policy would reject."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "label": {
+                    "type": "string",
+                    "description": "Restrict the output to rules matching this label.",
+                }
+            },
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "skeyd_suggest_label",
+        "description": (
+            "Propose a conventional label and environment variable name for a new "
+            "credential, given the URL or product it came from. Use this when asking a "
+            "human to add a key, so the name matches existing conventions."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "context": {
+                    "type": "string",
+                    "description": (
+                        "A URL or product description, e.g. "
+                        "'https://platform.openai.com/api-keys' or 'OpenRouter'."
+                    ),
+                },
+                "limit": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 10,
+                    "description": "How many suggestions to return (default 3).",
+                },
+            },
+            "required": ["context"],
+            "additionalProperties": False,
+        },
+    },
+)
+
+
+def tool_names() -> tuple[str, ...]:
+    return tuple(str(tool["name"]) for tool in TOOLS)
+
+
+def _as_anthropic(tool: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "name": tool["name"],
+        "description": tool["description"],
+        "input_schema": tool["input_schema"],
+    }
+
+
+def _as_openai(tool: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "type": "function",
+        "function": {
+            "name": tool["name"],
+            "description": tool["description"],
+            "parameters": tool["input_schema"],
+        },
+    }
+
+
+def _as_mcp(tool: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "name": tool["name"],
+        "description": tool["description"],
+        "inputSchema": tool["input_schema"],
+    }
+
+
+_FORMATTERS = {
+    "native": lambda tool: dict(tool),
+    "anthropic": _as_anthropic,
+    "openai": _as_openai,
+    "mcp": _as_mcp,
+}
+
+MANIFEST_FORMATS: Final = tuple(_FORMATTERS)
+
+
+def build_manifest(*, fmt: ManifestFormat = "native", version: str = "0.0.0") -> dict[str, Any]:
+    # Return the tool manifest in the requested dialect.
+    #
+    # The tool *definitions* are identical across formats; only the envelope shape differs, because the major frameworks disagree on where to put the schema.
+    formatter = _FORMATTERS.get(fmt)
+    if formatter is None:
+        from .errors import UsageError
+
+        raise UsageError(
+            f"Unknown manifest format {fmt!r}.",
+            hint=f"Choose one of: {', '.join(MANIFEST_FORMATS)}",
+        )
+
+    tools = [formatter(tool) for tool in TOOLS]
+    if fmt == "openai":
+        return {"tools": tools}
+    if fmt == "mcp":
+        return {"tools": tools}
+    return {
+        "agent_schema_version": AGENT_SCHEMA_VERSION,
+        "skeyd_version": version,
+        "tools": tools,
+        "notes": [
+            "No tool returns a plaintext credential. Injection happens inside skeyd.",
+            "Call skeyd_check_access before skeyd_run to avoid predictable denials.",
+            "A denial is a normal outcome, not an error: read error.hint and adapt.",
+        ],
+    }