keywright-server 0.0.1__py3-none-any.whl

keywright_server/__init__.py

@@ -0,0 +1,3 @@
+"""Keywright: just-in-time credential broker for AI agents."""
+
+__version__ = "0.0.1"

keywright_server/__main__.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import secrets
+import sys
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="keywright-server", description="Keywright server: JIT credential broker for AI agents")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    s = sub.add_parser("serve", help="run the server")
+    s.add_argument("--host")
+    s.add_argument("--port", type=int)
+    a = sub.add_parser("create-agent", help="create an agent and print its token once")
+    a.add_argument("name")
+    sub.add_parser("set-admin-password", help="set/reset the admin UI password (prompts)")
+    args = p.parse_args(argv)
+
+    from .config import settings
+
+    if args.cmd == "serve":
+        import uvicorn
+
+        from .web.app import create_app
+
+        uvicorn.run(create_app(), host=args.host or settings.host, port=args.port or settings.port, log_level="info",
+                    forwarded_allow_ips=settings.trusted_proxies or None)
+        return 0
+    if args.cmd == "create-agent":
+        return asyncio.run(_create_agent(args.name))
+    if args.cmd == "set-admin-password":
+        import getpass
+
+        pw = getpass.getpass("New admin password: ")
+        if pw != getpass.getpass("Repeat: "):
+            print("passwords differ", file=sys.stderr)
+            return 1
+        return asyncio.run(_set_password(pw))
+    return 1
+
+
+async def _create_agent(name: str) -> int:
+    from .db import init_db, session
+    from .mcp_server import hash_token
+    from .models import Agent
+
+    await init_db()
+    token = "kw_" + secrets.token_urlsafe(32)
+    async with session() as db:
+        db.add(Agent(name=name, token_hash=hash_token(token), token_prefix=token[:8]))
+        await db.commit()
+    print(token)
+    return 0
+
+
+async def _set_password(pw: str) -> int:
+    from .db import init_db, session
+    from .settings_store import warm
+    from .web.auth import set_password
+
+    await init_db()
+    async with session() as db:
+        await warm(db)
+        await set_password(db, pw)
+    print("ok")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

keywright_server/access.py

@@ -0,0 +1,131 @@
+"""Operation constraints shared by decisions, enforcement, and presentation."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def operation_detail(detail: dict | None) -> dict:
+    """The single operation an automatic request was made for; empty for pattern requests and for
+    batched requests, whose operations come from `operations()`."""
+    if "operations" in (detail or {}):
+        return {}
+    # Requests from before constraints recorded user=None for the default account; a non-default
+    # account always carries its own ssh/<host>/user/<name> pattern, so dropping the key is safe.
+    return {k: v for k, v in (detail or {}).items()
+            if k not in ("bundles", "hazards") and not (k == "user" and v is None)}
+
+
+def operations(detail: dict | None) -> list[tuple[list[str] | None, dict]]:
+    """(patterns, operation) pairs a decision binds to. A batched access_request stores one entry
+    per operation with the patterns it needs; an automatic request has one operation and the
+    request's own patterns (None here). Hazard flags travel with the operation for display but are
+    never part of what a grant binds to."""
+    if "operations" in (detail or {}):
+        return [(list(o["patterns"]), {k: v for k, v in o["operation"].items() if k != "hazards"})
+                for o in detail["operations"]]
+    op = operation_detail(detail)
+    return [(None, op)] if op else []
+
+
+def binds_exactly(detail: dict | None) -> bool:
+    return bool(operations(detail))
+
+
+def path_scoped(detail: dict | None) -> bool:
+    """A single file write. Its pattern already names host and path, so approving the patterns for
+    a short time means "any contents at this path, briefly": bounded in time instead of pinned to
+    a hash, which is what iterating on a script needs."""
+    return bool(detail) and "sha256" in detail and "operations" not in detail
+
+
+def hazards_of(detail: dict | None) -> list[dict]:
+    """Every hazard flag on a request or operation, whichever shape it has."""
+    if not detail:
+        return []
+    if "operations" in detail:
+        out: list[dict] = []
+        for o in detail["operations"]:
+            for h in (o.get("operation") or {}).get("hazards") or []:
+                if h not in out:
+                    out.append(h)
+        return out
+    return list(detail.get("hazards") or [])
+
+
+def hazard_level(detail: dict | None) -> str | None:
+    from keywright.hazards import worst
+
+    return worst(hazards_of(detail))
+
+
+def binds_operation(constraints: dict | None) -> bool:
+    """Whether constraints pin one exact operation (command, file digest, path or tool arguments),
+    as opposed to only the target identity."""
+    return bool(constraints) and any(k not in TARGET_KEYS for k in constraints)
+
+
+TARGET_KEYS = ("resource_id", "host", "user", "server", "gateway", "to_resource_id", "to_host", "to_user")
+
+
+def target_of(resource) -> dict:
+    """What a call with no operation (access_request, tools/list) is compared against: rules bound
+    only to this target apply, rules bound to an exact command or arguments do not."""
+    if resource.kind == "ssh":
+        return {"resource_id": resource.id, "host": resource.name, "user": resource.config.get("user") or "root"}
+    if resource.kind == "llm":
+        return {"resource_id": resource.id, "gateway": resource.name}
+    return {"resource_id": resource.id, "server": resource.name}
+
+
+def constraints_for(detail: dict | None, extent: str) -> dict | None:
+    return operation_constraints(operation_detail(detail), extent)
+
+
+def operation_constraints(operation: dict | None, extent: str) -> dict | None:
+    if not operation:
+        return None
+    if extent == "exact":
+        return operation
+    # Broader command/tool patterns still bind to the target identity and SSH account.
+    return {k: v for k, v in operation.items() if k in TARGET_KEYS} or None
+
+
+def operation_matches(constraints: dict | None, operation: dict | None) -> bool:
+    if not constraints:
+        return True
+    if operation is None or not constraints.keys() <= operation.keys():
+        return False
+    # JSON equality must distinguish true from 1, unlike Python container equality.
+    try:
+        return json.dumps(constraints, sort_keys=True, allow_nan=False) == json.dumps(
+            {k: operation[k] for k in constraints}, sort_keys=True, allow_nan=False)
+    except ValueError:
+        # NaN and Infinity are not JSON and never equal themselves, so they match nothing.
+        return False
+
+
+def constraint_label(constraints: dict[str, Any] | None) -> str:
+    if not constraints:
+        return "Permission patterns · any matching arguments"
+    if "command" in constraints:
+        return "Exact command"
+    if "arguments" in constraints:
+        return "Exact tool arguments"
+    if "sha256" in constraints:
+        return "Exact file contents"
+    if "path" in constraints:
+        return "Exact path"
+    if "user" in constraints:
+        return f"Permission patterns · as {constraints['user']}"
+    return "Permission patterns · bound to this target"
+
+
+def grant_constraints(grant, request=None) -> dict | None:
+    """Legacy automatic once grants bind through their request rather than a stored constraint."""
+    if grant.constraints:
+        return grant.constraints
+    if grant.scope == "once" and request and request.decision_options is None:
+        return operation_detail(request.detail) or None
+    return None

keywright_server/access_view.py

@@ -0,0 +1,144 @@
+"""Human-readable access inventory, including all authorization sources and restrictions."""
+
+from __future__ import annotations
+
+import math
+from collections import defaultdict
+
+from keywright.patterns import covers, overlaps
+from sqlalchemy import select
+
+from .access import constraint_label, grant_constraints
+from .models import AccessRequest, Agent, Grant, Policy, Resource, now
+
+
+def remaining(expires_at, at) -> str:
+    if expires_at is None:
+        return "Until used or revoked"
+    seconds = (expires_at - at).total_seconds()
+    return "Expired" if seconds <= 0 else f"{max(1, math.ceil(seconds / 60))}m remaining"
+
+
+async def overview(db) -> dict:
+    at = now()
+    agents = (await db.execute(select(Agent).order_by(Agent.name))).scalars().all()
+    resources = (await db.execute(select(Resource).order_by(Resource.kind, Resource.name))).scalars().all()
+    policies = (await db.execute(select(Policy).order_by(Policy.pattern))).scalars().all()
+    # Spent and expired grants are never revoked, so they pile up; leave them in the database.
+    grants = (await db.execute(select(Grant).where(
+        Grant.revoked_at.is_(None),
+        (Grant.expires_at.is_(None)) | (Grant.expires_at > at),
+        (Grant.uses_remaining.is_(None)) | (Grant.uses_remaining > 0),
+    ).order_by(Grant.created_at.desc()))).scalars().all()
+    grants = [g for g in grants if g.is_active(at, g.session_id)]
+    request_ids = {g.request_id for g in grants if g.request_id}
+    requests = {r.id: r for r in (await db.execute(select(AccessRequest).where(
+        AccessRequest.id.in_(request_ids)))).scalars().all()} if request_ids else {}
+    groups = defaultdict(list)
+    for g in grants:
+        groups[(g.agent_id, g.request_id or g.id)].append(g)
+    leases = []
+    for (agent_id, _), members in groups.items():
+        first = members[0]
+        req = requests.get(first.request_id)
+        leases.append({"agent_id": agent_id, "request": req, "grants": members,
+                       "constraints": grant_constraints(first, req),
+                       "label": constraint_label(grant_constraints(first, req)),
+                       "remaining": remaining(first.expires_at, at), "scope": first.scope,
+                       "session_id": first.session_id})
+    # Match every rule and grant against every target once, not once per agent.
+    scopes = {res.id: res.path_prefix + "/**" for res in resources}
+    rules_on = {rid: [p for p in policies if overlaps(p.pattern, scope)] for rid, scope in scopes.items()}
+    grants_on = {rid: [g for g in grants if overlaps(g.pattern, scope)] for rid, scope in scopes.items()}
+    by_agent = []
+    for agent in agents:
+        targets = []
+        for res in resources:
+            scope = scopes[res.id]
+            relevant = [p for p in rules_on[res.id] if p.agent_id in (None, agent.id)]
+            allows = [p for p in relevant if p.effect == "allow"]
+            denies = [p for p in relevant if p.effect == "deny"]
+            temporary = [g for g in grants_on[res.id] if g.agent_id == agent.id]
+            if agent.disabled:
+                state = "Suspended · new operations blocked"
+            elif any(not p.constraints and covers(p.pattern, scope) for p in denies):
+                state = "Denied for this target"
+            elif res.default_mode == "open":
+                state = "Allowed by default"
+            elif allows or temporary:
+                state = "Scoped access"
+            elif res.default_mode == "locked":
+                state = "Locked · standing rule required"
+            else:
+                state = "Approval required"
+            targets.append({"resource": res, "state": state, "allows": allows, "denies": denies,
+                            "temporary": len(temporary), "has_restrictions": bool(denies)})
+        by_agent.append({"agent": agent, "targets": targets,
+                         "leases": [g for g in leases if g["agent_id"] == agent.id]})
+    return {"access_agents": by_agent, "lease_count": len(leases), "target_count": len(resources),
+            "agent_count": len(agents)}
+
+
+# ---- the Grants page: agent -> resource -> approval, newest first ---------------------------------
+def grant_groups(grants: list[Grant], agents: dict[str, Agent], requests: dict[str, AccessRequest], at,
+                 *, include_inactive: bool = False) -> list[dict]:
+    """Grants grouped the way a human reads them: by agent, then by the host or server they reach,
+    then by the approval that made them (one decision can grant several paths). Every level is
+    ordered by its most recent approval. Inactive grants are left out unless asked for."""
+    from keywright.patterns import resource_of
+
+    from . import approvals
+
+    def state(g: Grant) -> str:
+        if g.is_active(at, g.session_id):
+            return "active"
+        return "revoked" if g.revoked_at else "ended"
+
+    kept = [g for g in grants if include_inactive or state(g) == "active"]
+    request_resources: dict[str, set[str]] = defaultdict(set)
+    for g in grants:
+        if g.request_id and state(g) == "active":
+            request_resources[g.request_id].add("/".join(resource_of(g.pattern) or ("?", "?")))
+
+    tree: dict[str, dict[str, dict[str, list[Grant]]]] = defaultdict(lambda: defaultdict(lambda: defaultdict(list)))
+    for g in kept:
+        res = "/".join(resource_of(g.pattern) or ("?", g.pattern))
+        tree[g.agent_id][res][g.request_id or f"grant:{g.id}"].append(g)
+
+    def latest(gs):
+        return max(g.created_at for g in gs)
+
+    out = []
+    for agent_id, by_res in tree.items():
+        hosts = []
+        for res, by_req in by_res.items():
+            approvals_ = []
+            for key, gs in by_req.items():
+                gs.sort(key=lambda g: g.pattern)
+                req = requests.get(gs[0].request_id) if gs[0].request_id else None
+                states = {state(g) for g in gs}
+                st = "active" if "active" in states else ("revoked" if states == {"revoked"} else "ended")
+                expiry = max((g.expires_at for g in gs if g.expires_at), default=None)
+                elsewhere = len(request_resources.get(gs[0].request_id or "", set()) - {res})
+                approvals_.append({
+                    "key": key, "grants": gs, "request": req, "approved_at": latest(gs), "state": st,
+                    "label": approvals.decision_label(req) if req else approvals.SCOPE_LABELS.get(gs[0].scope, gs[0].scope),
+                    "remaining": remaining(expiry, at) if st == "active" else None,
+                    "uses": [g.uses_remaining for g in gs if g.uses_remaining is not None],
+                    "session": next((g.session_id for g in gs if g.session_id), None),
+                    "constraints": [(g, grant_constraints(g, req)) for g in gs],
+                    "revoke": (f"/ui/requests/{req.id}/revoke" if req else f"/ui/grants/{gs[0].id}/revoke")
+                    if st == "active" else None,
+                    "elsewhere": elsewhere,
+                })
+            approvals_.sort(key=lambda a: a["approved_at"], reverse=True)
+            kind, _, name = res.partition("/")
+            hosts.append({"resource": res, "kind": kind, "name": name, "approvals": approvals_,
+                          "latest": approvals_[0]["approved_at"],
+                          "active": sum(1 for a in approvals_ if a["state"] == "active")})
+        hosts.sort(key=lambda h: h["latest"], reverse=True)
+        agent = agents.get(agent_id)
+        out.append({"agent": agent, "agent_id": agent_id, "name": agent.name if agent else "?", "hosts": hosts,
+                    "latest": hosts[0]["latest"], "active": sum(h["active"] for h in hosts)})
+    out.sort(key=lambda a: a["latest"], reverse=True)
+    return out

keywright_server/actions.py

@@ -0,0 +1,30 @@
+"""Compact authenticated actions for notification buttons: `<BODY>.<mac>`.
+
+A phone renders a button as a short opaque string and hands it back when tapped. The MAC is what
+carries the authority: knowing a request or nudge ID is not enough to act on one, and the strings
+stay short enough for Android's action payload limits, which a signed token would not.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+
+from .config import settings
+
+MAC_BYTES = 16  # 128 bits, the same budget itsdangerous spends, in a third of the characters
+
+
+def sign(body: str) -> str:
+    mac = hmac.new(settings.secret_key(), body.encode(), hashlib.sha256).digest()[:MAC_BYTES]
+    return body + "." + base64.urlsafe_b64encode(mac).decode().rstrip("=")
+
+
+def verify(action: str) -> str | None:
+    """The body of an action we signed, or None. Constant-time; never raises."""
+    try:
+        body, _ = action.rsplit(".", 1)
+    except ValueError:
+        return None
+    return body if hmac.compare_digest(action, sign(body)) else None