agent-credential-broker: fork of vaultwarden-agent-broker + OpenBao backend

Mechanical rename (package agent_credential_broker; entry points
agent-broker{,-mcp,-plugin}; env AGENT_BROKER_*; paths agent-broker;
agent-browser credential provider 'broker'; MCP server name agent-broker).

New backend 'openbao': stdlib-only HTTP client for OpenBao/Vault KV v2
(approle login or token file/env; metadata-only ref index; lazy re-login
on 401/403; token renewal). bitwarden-cli backend kept as transition.

agent_credential_broker/__init__.py

@@ -0,0 +1,9 @@
+"""agent-credential-broker: capability layer between agents and a vault.
+
+Invariant: agents may USE credentials through this broker, but can never
+RETRIEVE credential values. Every operation resolves a stable reference
+(``agent.ref`` custom field), enforces an item-scoped policy, executes a
+bounded adapter, and returns only sanitized metadata.
+"""
+
+__version__ = "0.1.0"

agent_credential_broker/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_credential_broker/adapters/__init__.py

@@ -0,0 +1,58 @@
+"""Adapter registry. Adapters receive (item, policy, params, config)
+in-process, inject the secret through an approved channel, execute a
+bounded operation, and return sanitized metadata only."""
+
+from __future__ import annotations
+
+from ..errors import denied
+
+
+def _load():
+    from . import http, ssh, git, cli_profile, browser
+    return {
+        "http": http.run,
+        "ssh": ssh.run,
+        "git": git.run,
+        "cli-profile": cli_profile.run,
+        "browser": browser.run,
+    }
+
+
+def _mods():
+    from . import http, ssh, git, cli_profile, browser
+    return {
+        "http": http,
+        "ssh": ssh,
+        "git": git,
+        "cli-profile": cli_profile,
+        "browser": browser,
+    }
+
+
+class _Registry:
+    _impl = None
+
+    @classmethod
+    def _mod(cls, adapter):
+        if cls._impl is None:
+            cls._impl = _mods()
+        mod = cls._impl.get(adapter)
+        if mod is None:
+            raise denied(f"unknown adapter {adapter!r}")
+        return mod
+
+    @classmethod
+    def validate(cls, adapter, item, policy, params, config):
+        """Pre-execution policy/argument validation -- runs BEFORE the
+        confirmation gate so target errors surface first."""
+        mod = cls._mod(adapter)
+        fn = getattr(mod, "validate", None)
+        if fn:
+            fn(item, policy, params, config)
+
+    @classmethod
+    def run(cls, adapter, item, policy, params, config):
+        return cls._mod(adapter).run(item, policy, params, config)
+
+
+registry = _Registry()

agent_credential_broker/adapters/browser.py

@@ -0,0 +1,115 @@
+"""Browser adapter.
+
+Preferred path (native provider): the agent runs
+
+    agent-browser auth login <name> --credential-provider broker \\
+        --item <agent.ref>
+
+agent-browser then invokes the broker's ``credential.read`` plugin and
+the secret flows plugin-stdout -> agent-browser, never through the
+agent. That plugin lives in plugin.py / entry point
+``agent-broker-plugin``.
+
+Broker-side operations implemented here:
+
+  browser_login          executes ``agent-browser auth login`` with the
+                         plugin flags (no secrets on argv -- resolution
+                         happens inside agent-browser via the plugin)
+  browser_fill_credential same mechanism on an existing page
+                         (--no-navigate + --url origin constraint +
+                         custom selectors from agent.* fields)
+
+Granular single-field fill via ``agent-browser fill`` is NOT offered:
+that command takes text on argv, which would expose the secret in
+/proc/<pid>/cmdline. If a site cannot be handled by the auth-login
+mechanism, the adapter raises UNSAFE_TOOL_INTEGRATION instead of
+downgrading to argv leaks.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+
+from ..config import socket_path
+from ..errors import invalid_argument, unsafe_tool_integration
+from ..policy import require_url_allowed
+from ..items import item_secrets
+from .common import clean_env, run_subprocess
+
+_SEL = re.compile(r"^[#.\[\]\w:='\"() >+~*-]{1,300}$")
+
+
+def _sel(v):
+    if v and not _SEL.match(v):
+        raise invalid_argument("bad selector")
+    return v
+
+
+def _agent_browser(config) -> str:
+    exe = shutil.which("agent-browser")
+    if not exe:
+        raise unsafe_tool_integration(
+            "agent-browser not installed; browser adapter unavailable")
+    return exe
+
+
+def validate(item, policy, params, config):
+    url = params.get("url") or (policy.uris[0] if policy.uris else None)
+    if not url:
+        raise invalid_argument("browser op requires a url")
+    require_url_allowed(policy, url)
+
+
+def run(item, policy, params, config):
+    op = params.get("op") or params.get("operation") or "browser_login"
+    url = params.get("url") or (policy.uris[0] if policy.uris else None)
+    if not url:
+        raise invalid_argument("browser op requires a url")
+    require_url_allowed(policy, url)
+    exe = _agent_browser(config)
+
+    argv = [exe, "auth", "login", policy.ref,
+            "--credential-provider", "broker",
+            "--item", policy.ref,
+            "--url", url]
+    us = _sel(params.get("username_selector") or policy.username_selector)
+    ps = _sel(params.get("password_selector") or policy.password_selector)
+    ss = _sel(params.get("submit_selector") or policy.submit_selector)
+    if us:
+        argv += ["--username-selector", us]
+    if ps:
+        argv += ["--password-selector", ps]
+    if ss:
+        argv += ["--submit-selector", ss]
+    if op == "browser_fill_credential":
+        argv.append("--no-navigate")
+    elif op != "browser_login":
+        raise invalid_argument(f"unsupported browser op {op!r}")
+    session = params.get("session")
+    if session:
+        if not re.match(r"^[\w.\-]{1,64}$", str(session)):
+            raise invalid_argument("bad session name")
+        argv += ["--session", str(session)]
+
+    plugin = shutil.which("agent-broker-plugin")
+    if not plugin:
+        raise unsafe_tool_integration(
+            "agent-broker-plugin not on PATH; browser adapter unavailable")
+    # child PATH must resolve the right node (agent-browser shebang) and
+    # the plugin binary; both live outside the base PATH on this host.
+    extra_paths = sorted({os.path.dirname(exe), os.path.dirname(plugin)})
+
+    env = clean_env({
+        "AGENT_BROKER_SOCKET": str(socket_path()),
+        "AGENT_BROWSER_CONFIG_DIR": os.environ.get(
+            "AGENT_BROWSER_CONFIG_DIR", os.path.expanduser("~/.agent-browser")),
+        # agent-browser session daemons live under $XDG_RUNTIME_DIR; without it
+        # the child cannot attach to an existing session browser.
+        "XDG_RUNTIME_DIR": os.environ.get("XDG_RUNTIME_DIR", ""),
+    }, prepend_paths=extra_paths)
+    res = run_subprocess(argv, env=env, timeout=120, secrets=item_secrets(item))
+    res["op"] = op
+    res["via"] = "agent-browser credential.read plugin"
+    return res

agent_credential_broker/adapters/cli_profile.py

@@ -0,0 +1,168 @@
+"""CLI-profile adapter: bounded subprocess execution of pre-declared
+tools only. There is intentionally NO generic "run with secret" -- every
+profile is a declarative allowlist:
+
+    {
+      "id": "example-cli",
+      "executable": "example-cli",
+      "injection": {"method": "env", "name": "EXAMPLE_TOKEN"},
+      "allowed_subcommands": ["list", "status"],
+      "arg_regex": "^[\\w .\\-/:]+$",
+      "forbidden_regex": "[;&|`$<>(){}\\[\\]]",
+      "target_hosts": ["api.example.com"],
+      "timeout": 30,
+      "max_output_bytes": 65536
+    }
+
+Injection methods (in order of preference):
+  stdin -- secret written to child stdin (no argv, no env, no file)
+  file  -- 0600 tmpfs file rendered from file_template ({SECRET}
+           placeholder); the child gets its PATH via env_name and/or
+           profile args_template entries containing {SECRET_FILE}
+  env   -- secret exported ONLY into the child environment
+  none  -- no secret reaches the child (metadata-only calls)
+
+Profile args_template entries are broker-supplied args (they may embed
+{SECRET_FILE} but NEVER the secret itself), so tools like curl can pick
+credentials up from config files without argv exposure. Agent-supplied
+args are validated separately.
+argv is never an injection channel.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import urllib.parse
+from pathlib import Path
+
+from ..config import profiles_dir
+from ..errors import denied, invalid_argument
+from ..items import item_secrets
+from .common import clean_env, run_subprocess, secret_dir, write_secret_file
+
+_DEFAULT_ARG_RE = r"^[\w ./:@\-+=%]+$"
+_DEFAULT_FORBIDDEN_RE = r"[;&|`$<>(){}\[\]\n!#]|(^|/)\.\.(/|$)"
+_MAX_ARGS = 64
+
+
+def load_profile(profile_id: str) -> dict:
+    if not profile_id or not re.match(r"^[\w.\-]+$", profile_id):
+        raise invalid_argument("bad profile id")
+    path = profiles_dir() / f"{profile_id}.json"
+    if not path.is_file():
+        raise denied(f"unknown cli profile {profile_id!r}")
+    try:
+        profile = json.loads(path.read_text())
+    except Exception:
+        raise denied(f"invalid cli profile {profile_id!r}")
+    if profile.get("id") != profile_id:
+        raise denied(f"profile id mismatch in {profile_id!r}")
+    if profile.get("disabled"):
+        raise denied(f"cli profile {profile_id!r} is disabled")
+    return profile
+
+
+def _validate_args(profile, args):
+    if not isinstance(args, list) or len(args) > _MAX_ARGS:
+        raise invalid_argument("bad args")
+    arg_re = re.compile(profile.get("arg_regex") or _DEFAULT_ARG_RE)
+    forbidden = profile.get("forbidden_regex")
+    for a in args:
+        if not isinstance(a, str) or not a or len(a) > 500:
+            raise invalid_argument("bad argument")
+        if not arg_re.match(a):
+            raise invalid_argument(f"argument {a!r} rejected by profile arg_regex")
+        if forbidden and re.search(forbidden, a):
+            raise invalid_argument(f"argument {a!r} rejected by profile forbidden_regex")
+    subs = profile.get("allowed_subcommands")
+    if subs:
+        positional = [a for a in args if not a.startswith("-")]
+        if not positional or positional[0] not in subs:
+            raise invalid_argument(
+                f"first positional must be one of {subs}")
+    targets = {h.lower() for h in (profile.get("target_hosts") or [])}
+    if targets:
+        for a in args:
+            if "://" in a:
+                host = (urllib.parse.urlparse(a).hostname or "").lower()
+                if host not in targets:
+                    raise invalid_argument(
+                        f"url target {host!r} not in profile target_hosts")
+
+
+def validate(item, policy, params, config):
+    profile_id = params.get("profile")
+    profile = load_profile(profile_id)
+    if policy.cli_profile and policy.cli_profile != profile_id:
+        raise denied(f"credential {policy.ref!r} is bound to profile {policy.cli_profile!r}")
+    _validate_args(profile, params.get("args") or [])
+
+
+def run(item, policy, params, config):
+    profile_id = params.get("profile")
+    profile = load_profile(profile_id)
+    if policy.cli_profile and policy.cli_profile != profile_id:
+        raise denied(f"credential {policy.ref!r} is bound to profile {policy.cli_profile!r}")
+
+    executable = profile.get("executable") or ""
+    if "/" in executable or ".." in executable:
+        raise denied("profile executable must be a bare name")
+    exe = shutil.which(executable)
+    if not exe:
+        raise denied(f"executable {executable!r} not found")
+
+    args = params.get("args") or []
+    _validate_args(profile, args)
+
+    injection = profile.get("injection") or {}
+    method = injection.get("method")
+    secret = item.get("password") or ""
+    secrets = item_secrets(item)
+    timeout = int(profile.get("timeout") or 30)
+    argv = [exe] + [str(a) for a in args]
+    input_text = None
+
+    if method == "stdin":
+        input_text = secret + "\n"
+        env = clean_env(profile.get("env") or {})
+    elif method == "file":
+        with secret_dir() as d:
+            sfile = d / "secret"
+            template = injection.get("file_template") or "{SECRET}"
+            if "{SECRET}" not in template:
+                raise denied("file_template must contain {SECRET}")
+            write_secret_file(sfile, template.replace("{SECRET}", secret))
+            env = clean_env(profile.get("env") or {})
+            env_name = injection.get("env_name")
+            if env_name:
+                env[env_name] = str(sfile)
+            extra = [a.replace("{SECRET_FILE}", str(sfile))
+                     for a in (profile.get("args_template") or [])]
+            argv = [exe] + extra + argv[1:]
+            res = run_subprocess(argv, env=env, input_text=None,
+                                 timeout=timeout, secrets=secrets)
+            res["profile"] = profile_id
+            res["injection"] = "file"
+            return _cap(profile, res)
+    elif method == "env":
+        env = clean_env(profile.get("env") or {})
+        env[injection.get("name") or "CREDENTIAL"] = secret
+    else:
+        env = clean_env(profile.get("env") or {})
+        if method not in (None, "none"):
+            raise denied(f"unknown injection method {method!r}")
+
+    res = run_subprocess(argv, env=env, input_text=input_text,
+                         timeout=timeout, secrets=secrets)
+    res["profile"] = profile_id
+    res["injection"] = method or "none"
+    return _cap(profile, res)
+
+
+def _cap(profile, res):
+    cap = int(profile.get("max_output_bytes") or 65536)
+    res["stdout"] = res["stdout"][:cap]
+    res["stderr"] = res["stderr"][:cap]
+    return res

agent_credential_broker/adapters/common.py

@@ -0,0 +1,117 @@
+"""Shared helpers for adapters: bounded subprocesses and askpass scripts.
+
+Secret-bearing helper files are created only under
+$XDG_RUNTIME_DIR/agent-broker/tmp (tmpfs, 0700 dir, 0600
+files) and deleted immediately after use. Secrets never appear on argv.
+"""
+
+from __future__ import annotations
+
+import os
+import secrets as _secrets
+import subprocess
+from contextlib import contextmanager
+from pathlib import Path
+
+from ..config import tmp_dir
+from ..sanitize import sanitize_text, sanitize_bytes
+
+
+def make_secret_dir() -> Path:
+    d = tmp_dir() / _secrets.token_hex(12)
+    d.mkdir(mode=0o700)
+    return d
+
+
+def write_secret_file(path: Path, value: str):
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    with os.fdopen(fd, "w") as fh:
+        fh.write(value)
+
+
+def write_askpass(dirpath: Path, user_file: Path | None, pass_file: Path) -> Path:
+    """askpass script reads values from sibling files -- the secret is
+    never inside the script itself or on any argv."""
+    script = dirpath / "askpass.sh"
+    lines = [
+        "#!/bin/sh",
+        "case \"$1\" in",
+    ]
+    if user_file is not None:
+        lines += [
+            "  *sername*|*ogin*) cat %s ;;",
+            f"  *) cat {pass_file} ;;",
+        ]
+    else:
+        lines.append(f"  *) cat {pass_file} ;;")
+    lines.append("esac")
+    if user_file is not None:
+        lines[3] = lines[3] % user_file
+    script.write_text("\n".join(lines) + "\n")
+    os.chmod(script, 0o700)
+    return script
+
+
+def run_subprocess(argv: list[str], *, env: dict | None = None, input_text: str | None = None,
+                   timeout: int = 60, secrets: list[str] = ()) -> dict:
+    """Run argv without a shell. Returns sanitized {exit_code, stdout,
+    stderr}. Never raises the child's output raw."""
+    try:
+        proc = subprocess.run(
+            argv,
+            env=env,
+            input=input_text,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        rc, raw_out, raw_err = proc.returncode, proc.stdout, proc.stderr
+        timed_out = False
+    except subprocess.TimeoutExpired as e:
+        rc, timed_out = 124, True
+        raw_out = (e.stdout or b"").decode("utf-8", "replace") if isinstance(e.stdout, bytes) else (e.stdout or "")
+        raw_err = ((e.stderr or b"").decode("utf-8", "replace") if isinstance(e.stderr, bytes) else (e.stderr or "")) + \
+            f"\n[timeout after {timeout}s]"
+    out = sanitize_bytes(raw_out.encode(), [s.encode() for s in secrets if s])
+    err = sanitize_bytes(raw_err.encode(), [s.encode() for s in secrets if s])
+    result = {
+        "exit_code": rc,
+        "stdout": sanitize_text(out.decode("utf-8", "replace"), secrets),
+        "stderr": sanitize_text(err.decode("utf-8", "replace"), secrets),
+    }
+    if timed_out:
+        result["timed_out"] = True
+    return result
+
+
+@contextmanager
+def secret_dir():
+    d = make_secret_dir()
+    try:
+        yield d
+    finally:
+        for child in d.iterdir():
+            try:
+                child.unlink()
+            except OSError:
+                pass
+        try:
+            d.rmdir()
+        except OSError:
+            pass
+
+
+def clean_env(extra: dict | None = None, prepend_paths: list[str] = ()) -> dict:
+    """Minimal environment for secret-bearing children: no inherited
+    credential variables are added beyond what the adapter explicitly
+    injects. prepend_paths lists directories that must precede the base
+    PATH (e.g. the dir of a resolved executable whose shebang needs a
+    specific interpreter)."""
+    env = {
+        "PATH": ":".join([*prepend_paths, "/usr/local/bin", "/usr/bin", "/bin"]),
+        "HOME": os.environ.get("HOME", "/"),
+        "LANG": "C.UTF-8",
+    }
+    if extra:
+        env.update(extra)
+    return env

agent_credential_broker/adapters/git.py

@@ -0,0 +1,135 @@
+"""Git adapter: clone/fetch/push over HTTPS with askpass auth.
+
+The token/password is supplied through a generated GIT_ASKPASS script
+that cats 0600 runtime-tmpfs files -- it never appears on argv, never
+inside the remote URL, and never in output (output is sanitized too).
+Credentials embedded in URLs (https://user:pass@host) are rejected.
+"""
+
+from __future__ import annotations
+
+import configparser
+import os
+import re
+import shutil
+import urllib.parse
+from pathlib import Path
+
+from ..errors import invalid_argument, origin_denied, unsafe_tool_integration
+from ..policy import require_url_allowed
+from ..items import item_secrets
+from .common import (clean_env, run_subprocess, secret_dir, write_askpass,
+                     write_secret_file)
+
+_OPS = {"clone", "fetch", "push"}
+_REFSPEC_OK = re.compile(r"^[\w\-./:+]+$")
+
+
+def _validate_repo_url(item, policy, url):
+    if not url:
+        raise invalid_argument("missing repository url")
+    if url.startswith("git@") or url.startswith("ssh://"):
+        raise unsafe_tool_integration(
+            "git: ssh remotes not wired to vault credentials in this phase; use https")
+    p = urllib.parse.urlparse(url)
+    if p.scheme not in ("https", "http"):
+        raise invalid_argument(f"unsupported git remote scheme {p.scheme!r}")
+    if "@" in (p.netloc or ""):
+        raise invalid_argument("credentials must not be embedded in the remote URL")
+    require_url_allowed(policy, url)
+
+
+def _check_workdir(config_roots, workdir):
+    wd = Path(workdir).resolve()
+    roots = [Path(r).expanduser().resolve() for r in config_roots] or [Path.home()]
+    if not any(str(wd).startswith(str(r) + os.sep) or wd == r for r in roots):
+        raise origin_denied("git", f"workdir {wd} outside allowed roots")
+    if not (wd / ".git").is_dir():
+        raise invalid_argument(f"{wd} is not a git worktree")
+    return wd
+
+
+def _remote_url(workdir: Path, remote: str) -> str:
+    """Read the remote's URL straight from .git/config -- the credential
+    will actually go there, so THAT is the URL we validate, not whatever
+    the agent claimed in `repository`."""
+    cfg = configparser.RawConfigParser()
+    cfg.read(workdir / ".git" / "config")
+    try:
+        url = cfg.get(f'remote "{remote}"', "url")
+    except configparser.Error:
+        raise invalid_argument(f"remote {remote!r} has no url configured")
+    if "://" in url and "@" in urllib.parse.urlparse(url).netloc:
+        raise invalid_argument("remote URL has embedded credentials")
+    return url
+
+
+def validate(item, policy, params, config):
+    op = params.get("op") or params.get("operation")
+    if op not in _OPS:
+        raise invalid_argument(f"git op must be one of {sorted(_OPS)}")
+    _validate_repo_url(item, policy, params.get("repository") or "")
+    if op != "clone":
+        workdir = _check_workdir(config.git_workdir_roots, params.get("workdir") or ".")
+        remote = params.get("remote") or "origin"
+        remote_url = _remote_url(workdir, remote)
+        _validate_repo_url(item, policy, remote_url)
+
+
+def run(item, policy, params, config):
+    op = params.get("op") or params.get("operation")
+    if op not in _OPS:
+        raise invalid_argument(f"git op must be one of {sorted(_OPS)}")
+    repo_url = params.get("repository") or ""
+    _validate_repo_url(item, policy, repo_url)
+
+    username = item.get("username")
+    password = item.get("password")
+    if not password:
+        raise unsafe_tool_integration("git: item has no token/password")
+    secrets = item_secrets(item)
+
+    git = shutil.which("git") or "/usr/bin/git"
+    with secret_dir() as d:
+        ufile = d / "user"
+        pfile = d / "pass"
+        write_secret_file(ufile, username or "oauth2")
+        write_secret_file(pfile, password)
+        askpass = write_askpass(d, ufile, pfile)
+        env = clean_env({
+            "GIT_ASKPASS": str(askpass),
+            "GIT_TERMINAL_PROMPT": "0",
+        })
+
+        if op == "clone":
+            dest = params.get("dest")
+            if not dest:
+                raise invalid_argument("clone requires dest")
+            argv = [git, "clone", "--", repo_url, str(dest)]
+        else:
+            workdir = _check_workdir(config.git_workdir_roots, params.get("workdir") or ".")
+            remote = params.get("remote") or "origin"
+            if not _REFSPEC_OK.match(remote):
+                raise invalid_argument("bad remote name")
+            remote_url = _remote_url(workdir, remote)
+            if remote_url.startswith("git@") or remote_url.startswith("ssh://"):
+                raise unsafe_tool_integration(
+                    "git: ssh remotes not wired to vault credentials in this phase")
+            _validate_repo_url(item, policy, remote_url)
+            claimed = urllib.parse.urlparse(repo_url).netloc
+            actual = urllib.parse.urlparse(remote_url).netloc
+            if claimed.lower() != actual.lower():
+                raise origin_denied(policy.ref,
+                                    f"repository claim {claimed!r} != remote {actual!r}")
+            argv = [git, "-C", str(workdir)]
+            if op == "fetch":
+                argv += ["fetch", "--", remote]
+            else:
+                refspec = params.get("refspec") or params.get("branch") or "HEAD"
+                if not _REFSPEC_OK.match(refspec):
+                    raise invalid_argument("bad refspec")
+                argv += ["push", "--", remote, refspec]
+        result = run_subprocess(argv, env=env, timeout=180, secrets=secrets)
+        result["op"] = op
+        result["repository"] = urllib.parse.urlparse(repo_url).netloc
+        return result

agent_credential_broker/adapters/http.py

@@ -0,0 +1,113 @@
+"""HTTP adapter: credential-bearing requests without exposing headers.
+
+Supported auth types (from agent.auth_type):
+  bearer -> Authorization: Bearer <password-field>
+  basic  -> Authorization: Basic base64(username:password)
+  none   -> no credential header (metadata-only requests)
+
+Destination is origin-validated against agent.allowed_urls / item URIs.
+Redirects are NOT followed by default; with follow_redirects=true each
+hop is re-validated before the credential is attached.
+"""
+
+from __future__ import annotations
+
+import base64
+import urllib.error
+import urllib.request
+
+from ..errors import invalid_argument
+from ..policy import require_url_allowed
+from ..sanitize import sanitize_headers, sanitize_text
+from ..items import item_secrets
+
+_METHODS = {"GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"}
+_FORBIDDEN_REQ_HEADERS = {"authorization", "proxy-authorization", "cookie", "set-cookie", "host", "content-length"}
+_MAX_BODY = 64 * 1024
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *a, **k):
+        return None
+
+
+def _auth_header(item, policy) -> tuple[str, str] | None:
+    if policy.auth_type == "none":
+        return None
+    password = item.get("password") or ""
+    if policy.auth_type == "bearer":
+        return ("Authorization", f"Bearer {password}")
+    user = item.get("username") or ""
+    return ("Authorization", "Basic " + base64.b64encode(f"{user}:{password}".encode()).decode())
+
+
+def validate(item, policy, params, config):
+    method = (params.get("method") or "GET").upper()
+    if method not in _METHODS:
+        raise invalid_argument(f"unsupported HTTP method {method!r}")
+    require_url_allowed(policy, params.get("url") or "")
+
+
+def run(item, policy, params, config):
+    url = params.get("url") or ""
+    method = (params.get("method") or "GET").upper()
+    if method not in _METHODS:
+        raise invalid_argument(f"unsupported HTTP method {method!r}")
+    require_url_allowed(policy, url)
+
+    headers = {}
+    for k, v in (params.get("headers") or {}).items():
+        if k.lower() in _FORBIDDEN_REQ_HEADERS:
+            raise invalid_argument(f"request header {k!r} not allowed")
+        headers[k] = str(v)
+    auth = _auth_header(item, policy)
+    if auth:
+        headers[auth[0]] = auth[1]
+
+    body = params.get("body")
+    if body is not None:
+        body = str(body).encode()
+        if len(body) > _MAX_BODY:
+            raise invalid_argument("request body too large")
+
+    secrets = item_secrets(item)
+    if auth:
+        secrets.append(auth[1])
+        secrets.append(auth[1].split(" ", 1)[-1])
+
+    opener = urllib.request.build_opener(_NoRedirect) if not params.get("follow_redirects") else urllib.request.build_opener()
+    if params.get("follow_redirects"):
+        # urllib would follow redirects automatically; revalidation of
+        # each hop happens via a custom handler would be ideal, so we
+        # conservatively refuse cross-origin redirects by checking the
+        # final URL afterwards.
+        pass
+    req = urllib.request.Request(url, data=body, headers=headers, method=method)
+    try:
+        with opener.open(req, timeout=20) as resp:
+            status = resp.status
+            resp_headers = dict(resp.headers.items())
+            final_url = resp.geturl()
+            data = resp.read(256 * 1024 + 1)
+    except urllib.error.HTTPError as e:
+        status = e.code
+        resp_headers = dict(e.headers.items()) if e.headers else {}
+        final_url = e.geturl()
+        data = e.read(256 * 1024 + 1)
+    except urllib.error.URLError:
+        raise invalid_argument("request failed (network error)")
+    except ValueError:
+        raise invalid_argument("malformed URL or redirect")
+
+    if params.get("follow_redirects"):
+        require_url_allowed(policy, final_url)
+
+    truncated = len(data) > 256 * 1024
+    data = data[:256 * 1024]
+    return {
+        "status": status,
+        "final_url": sanitize_text(final_url, secrets),
+        "headers": sanitize_headers(resp_headers, secrets),
+        "body": sanitize_text(data.decode("utf-8", "replace"), secrets),
+        "truncated": truncated,
+    }

agent_credential_broker/adapters/ssh.py

@@ -0,0 +1,100 @@
+"""SSH adapter: broker-managed ssh authentication.
+
+Two credential modes:
+  * agent.ssh_key_path set  -> uses that existing local private key file
+    (path metadata only -- key bytes never move through the broker)
+  * otherwise               -> password auth via SSH_ASKPASS, where the
+    password is a 0600 file under the runtime tmpfs that the generated
+    askpass script cats at prompt time. Never on argv.
+
+The remote command is passed as a single argv element to ssh -- no local
+shell interpolation is possible.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+
+from ..config import state_dir
+from ..errors import invalid_argument, unsafe_tool_integration
+from ..policy import require_host_allowed
+from ..items import item_secrets
+from .common import (clean_env, run_subprocess, secret_dir, write_askpass,
+                     write_secret_file)
+
+
+def _known_hosts():
+    """Broker-managed known_hosts (TOFU trust stays in the broker's own
+    state dir instead of silently writing to the user's ~/.ssh)."""
+    d = state_dir() / "ssh"
+    d.mkdir(mode=0o700, parents=True, exist_ok=True)
+    p = d / "known_hosts"
+    if not p.exists():
+        p.touch(mode=0o600)
+    return p
+
+_CMD_MAX = 2000
+_DANGEROUS = re.compile(r"[;&|`$<>]|^\s*(sudo\s+)?(rm|dd|mkfs|shutdown|reboot|poweroff)\b")
+
+
+def validate(item, policy, params, config):
+    host = params.get("host") or ""
+    command = params.get("command") or ""
+    if not command or len(command) > _CMD_MAX:
+        raise invalid_argument("missing or oversized command")
+    if _DANGEROUS.search(command):
+        raise invalid_argument("command rejected by safety policy")
+    require_host_allowed(policy, host)
+
+
+def run(item, policy, params, config):
+    host = params.get("host") or ""
+    command = params.get("command") or ""
+    port = int(params.get("port") or 22)
+    if not command or len(command) > _CMD_MAX:
+        raise invalid_argument("missing or oversized command")
+    if _DANGEROUS.search(command):
+        raise invalid_argument("command rejected by safety policy")
+    require_host_allowed(policy, host)
+
+    ssh = shutil.which("ssh") or "/usr/bin/ssh"
+    user = policy.ssh_user or item.get("username") or "root"
+    target = f"{user}@{host}"
+    argv = [
+        ssh,
+        "-o", "BatchMode=no",
+        "-o", "ConnectTimeout=15",
+        "-o", "StrictHostKeyChecking=accept-new",
+        "-o", f"UserKnownHostsFile={_known_hosts()}",
+        "-o", "NumberOfPasswordPrompts=1",
+        "-o", "IdentitiesOnly=yes",
+        "-p", str(port),
+        target,
+        command,
+    ]
+    secrets = item_secrets(item)
+    key_path = policy.ssh_key_path
+    if key_path:
+        if not os.path.isfile(key_path):
+            raise unsafe_tool_integration("ssh: agent.ssh_key_path does not exist")
+        argv = argv[:-2] + ["-i", key_path] + argv[-2:]
+        result = run_subprocess(argv, env=clean_env(), timeout=30, secrets=secrets)
+    else:
+        password = item.get("password")
+        if not password:
+            raise unsafe_tool_integration("ssh: no key path and no password on item")
+        with secret_dir() as d:
+            pwfile = d / "pw"
+            write_secret_file(pwfile, password)
+            askpass = write_askpass(d, None, pwfile)
+            env = clean_env({
+                "SSH_ASKPASS": str(askpass),
+                "SSH_ASKPASS_REQUIRE": "force",
+                "DISPLAY": "broker:0",
+            })
+            result = run_subprocess(argv, env=env, timeout=30, secrets=secrets)
+    result["host"] = host
+    result["auth"] = "key" if key_path else "password-askpass"
+    return result

agent_credential_broker/audit.py

@@ -0,0 +1,41 @@
+"""Audit logging -- metadata only, never secret material."""
+
+from __future__ import annotations
+
+import json
+import threading
+from datetime import datetime, timezone
+
+from .config import audit_log_path
+
+_lock = threading.Lock()
+
+
+def _scrub(record: dict) -> dict:
+    return {k: v for k, v in record.items() if v is not None}
+
+
+def audit(operation: str, *, ref=None, adapter=None, target=None,
+          result="ok", error_code=None, detail=None):
+    entry = _scrub({
+        "ts": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "op": operation,
+        "ref": ref,
+        "adapter": adapter,
+        "target": target,
+        "result": result,
+        "error": error_code,
+        "detail": detail,
+    })
+    line = json.dumps(entry, sort_keys=True)
+    # Belt-and-suspenders: audit lines must never carry secret material.
+    for banned in ("password", "secret", "token", "key"):
+        if isinstance(detail, str) and banned in detail.lower():
+            entry["detail"] = "REDACTED_DETAIL"
+            line = json.dumps(_scrub(entry), sort_keys=True)
+            break
+    try:
+        with _lock, open(audit_log_path(), "a") as fh:
+            fh.write(line + "\n")
+    except OSError:
+        pass  # audit must never break operations

agent_credential_broker/backends/__init__.py

@@ -0,0 +1,70 @@
+"""Vault backend abstraction -- the ONLY layer that talks to the vault.
+
+    bitwarden-cli    official `bw` subprocesses against a
+                     Bitwarden-compatible server (transition backend).
+    openbao          OpenBao/Vault HTTP API (KV v2 + AppRole), stdlib
+                     urllib only -- the target backend for agent
+                     credentials.
+
+A failing backend surfaces as VAULT_BACKEND_ERROR; there is no fallback.
+
+The backend owns authentication, the unlocked session and vault reads.
+Everything else (policy, refs, adapters, sanitizer, MCP, unix socket)
+is backend-agnostic.
+"""
+
+from __future__ import annotations
+
+from ..errors import BrokerError
+
+
+class VaultBackend:
+    """Interface consumed by BrokerCore.
+
+    unlock(password)    authenticate + establish session (raises
+                        UNLOCK_FAILED on bad password, VAULT_BACKEND_ERROR
+                        otherwise)
+    lock()              invalidate session + drop in-memory material
+    list_metadata()     items with secret fields stripped (ref index)
+    get_item(item_id)   full normalized item, fetched on demand
+    """
+
+    name = "abstract"
+
+    def __init__(self, config):
+        self.config = config
+
+    def configured(self) -> bool:
+        raise NotImplementedError
+
+    def unlock(self, password: str) -> None:
+        raise NotImplementedError
+
+    def lock(self) -> None:
+        raise NotImplementedError
+
+    def logout(self) -> None:
+        """End the vault session AND the stored account login. Default
+        equals lock() for backends without a persistent login."""
+        self.lock()
+
+    def list_metadata(self) -> list[dict]:
+        raise NotImplementedError
+
+    def get_item(self, item_id: str) -> dict:
+        raise NotImplementedError
+
+
+def make_backend(config) -> VaultBackend:
+    name = config.vault_backend
+    if name == "bitwarden-cli":
+        from .bwcli import BitwardenCliBackend
+        return BitwardenCliBackend(config)
+    if name == "openbao":
+        from .openbao import OpenBaoBackend
+        return OpenBaoBackend(config)
+    raise BrokerError(
+        "UNCONFIGURED",
+        f"unknown vault_backend {name!r} "
+        "(supported: 'bitwarden-cli', 'openbao')",
+    )

agent_credential_broker/backends/bwcli.py

@@ -0,0 +1,216 @@
+"""Official Bitwarden CLI vault backend.
+
+All vault cryptography (master-key derivation, EncString, sync format)
+is delegated to the maintained `bw` client. The broker spawns it as a
+subprocess with a dedicated, isolated profile:
+
+    vault server --(bw)--> private pipe --> broker --> adapters
+
+Secret channels:
+    BW_CLIENTID / BW_CLIENTSECRET  login    child env only
+    AGENT_BROKER_MASTER_PW         unlock   child env only (--passwordenv)
+    BW_SESSION                     data ops child env only, held in memory,
+                                  never persisted, invalidated by `bw lock`
+
+Secrets never appear on argv and `bw` stdout/stderr is never forwarded
+raw -- errors surface sanitized excerpts only.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from .. import errors
+from ..config import read_secret_file
+from ..errors import BrokerError, backend_error
+from ..items import metadata_projection, normalize_bw_item
+from ..sanitize import sanitize_text
+from . import VaultBackend
+
+_PW_ENV = "AGENT_BROKER_MASTER_PW"  # env var NAME only -- value lives in child env
+_TIMEOUT = 90
+
+
+class BitwardenCliBackend(VaultBackend):
+    name = "bitwarden-cli"
+
+    def __init__(self, config):
+        super().__init__(config)
+        self.bw = config.bw_path or shutil.which("bw")
+        self._session: str | None = None
+        self._meta: list[dict] = []
+
+    # -- plumbing --------------------------------------------------------
+
+    def configured(self) -> bool:
+        return (bool(self.bw) and Path(self.bw).exists()
+                and self.config.client_id_file.exists()
+                and self.config.client_secret_file.exists())
+
+    def _appdata(self) -> Path:
+        d = self.config.bw_appdata_dir
+        d.mkdir(mode=0o700, parents=True, exist_ok=True)
+        os.chmod(d, 0o700)
+        return d
+
+    def _env(self, extra: dict | None = None) -> dict:
+        """Child-scoped environment. PATH puts the directory containing
+        `bw` first so its `#!/usr/bin/env node` shebang resolves the same
+        Node.js the CLI was installed with (a stale system node breaks
+        the WASM crypto layer). The npm `bw` is a symlink into lib/ --
+        do NOT resolve it: the bin dir itself holds the right `node`."""
+        bw_dir = str(Path(self.bw).parent)
+        env = {
+            "PATH": f"{bw_dir}:/usr/local/bin:/usr/bin:/bin",
+            "HOME": os.environ.get("HOME", "/"),
+            "LANG": "C.UTF-8",
+            "BITWARDENCLI_APPDATA_DIR": str(self._appdata()),
+        }
+        if extra:
+            env.update(extra)
+        return env
+
+    def _run(self, args: list[str], *, extra_env=None, secrets=(), stdin=None,
+             timeout=_TIMEOUT) -> tuple[int, str, str]:
+        """Spawn `bw` with secrets confined to child env/stdin. Returns
+        RAW stdout/stderr -- callers must sanitize before surfacing."""
+        env = self._env(extra_env)
+        try:
+            proc = subprocess.run(
+                [self.bw, *args], env=env, input=stdin,
+                capture_output=True, text=True, timeout=timeout,
+            )
+        except FileNotFoundError:
+            raise backend_error(f"bitwarden CLI not found at {self.bw}")
+        except subprocess.TimeoutExpired:
+            raise backend_error(f"bw {args[0] if args else '?'} timed out")
+        return proc.returncode, proc.stdout, proc.stderr
+
+    def _fail(self, op: str, err: str, secrets) -> BrokerError:
+        detail = sanitize_text(err.strip(), secrets)[:300]
+        low = detail.lower()
+        if "vault is locked" in low or "not logged in" in low:
+            return errors.locked()
+        return backend_error(f"bw {op} failed: {detail or 'unknown error'}")
+
+    def _ok(self, op: str, rc: int, out: str, err: str, secrets=()) -> str:
+        if rc != 0:
+            raise self._fail(op, err, secrets)
+        return out
+
+    def _bw_status(self) -> dict:
+        rc, out, err = self._run(["status"])
+        self._ok("status", rc, out, err)
+        try:
+            return json.loads(out)
+        except json.JSONDecodeError:
+            raise backend_error("unparseable bw status output")
+
+    # -- VaultBackend -----------------------------------------------------
+
+    def _ensure_server(self, st: dict) -> dict:
+        if (st.get("serverUrl") or "").rstrip("/") != self.config.vault_url:
+            rc, out, err = self._run(["config", "server", self.config.vault_url])
+            self._ok("config", rc, out, err)
+        return st
+
+    def _login(self):
+        client_id = read_secret_file(self.config.client_id_file)
+        client_secret = read_secret_file(self.config.client_secret_file)
+        secrets = (client_id, client_secret)
+        try:
+            rc, out, err = self._run(
+                ["login", "--apikey", "--nointeraction"],
+                extra_env={"BW_CLIENTID": client_id,
+                           "BW_CLIENTSECRET": client_secret},
+                secrets=secrets)
+            if rc != 0:
+                raise self._fail("login", err, secrets)
+            # stdout may carry a session key -- captured, never surfaced
+        finally:
+            client_id = client_secret = None
+
+    def unlock(self, password: str) -> None:
+        st = self._ensure_server(self._bw_status())
+        if st.get("status") == "unauthenticated":
+            self._login()
+        secrets = (password,)
+        try:
+            rc, out, err = self._run(
+                ["unlock", "--passwordenv", _PW_ENV, "--raw", "--nointeraction"],
+                extra_env={_PW_ENV: password}, secrets=secrets)
+            if rc != 0 or not out.strip():
+                clean = sanitize_text(err.strip(), secrets)
+                detail = ([l for l in clean.splitlines() if l.strip()] or [""])[-1][:200]
+                raise BrokerError(
+                    "UNLOCK_FAILED",
+                    f"unlock failed: {detail or 'master password rejected'}")
+            self._session = out.strip().splitlines()[-1].strip()
+        finally:
+            password = None
+        self._sync()
+        raw = self._list_items_raw()
+        self._meta = [metadata_projection(normalize_bw_item(i)) for i in raw]
+        raw = None
+
+    def lock(self) -> None:
+        try:
+            if self._session:
+                self._run(["lock", "--nointeraction"], secrets=(self._session,))
+        except errors.BrokerError:
+            pass
+        finally:
+            self._session = None
+            self._meta = []
+
+    def logout(self) -> None:
+        try:
+            self._run(["logout", "--nointeraction"], secrets=(self._session,) if self._session else ())
+        except errors.BrokerError:
+            pass
+        finally:
+            self._session = None
+            self._meta = []
+
+    def list_metadata(self) -> list[dict]:
+        return self._meta
+
+    def _data_env(self) -> dict:
+        if not self._session:
+            raise errors.locked()
+        return {"BW_SESSION": self._session}
+
+    def _sync(self):
+        secrets = (self._session,)
+        rc, out, err = self._run(["sync", "--nointeraction"],
+                                 extra_env=self._data_env(), secrets=secrets)
+        self._ok("sync", rc, out, err, secrets)
+
+    def _list_items_raw(self) -> list[dict]:
+        secrets = (self._session,)
+        rc, out, err = self._run(["list", "items", "--nointeraction"],
+                                 extra_env=self._data_env(), secrets=secrets)
+        self._ok("list items", rc, out, err, secrets)
+        try:
+            data = json.loads(out)
+        except json.JSONDecodeError:
+            raise backend_error("unparseable bw list output")
+        if not isinstance(data, list):
+            raise backend_error("unexpected bw list output")
+        return data
+
+    def get_item(self, item_id: str) -> dict:
+        secrets = (self._session,)
+        rc, out, err = self._run(
+            ["get", "item", str(item_id), "--nointeraction"],
+            extra_env=self._data_env(), secrets=secrets)
+        if rc != 0:
+            raise self._fail("get item", err, secrets)
+        try:
+            return normalize_bw_item(json.loads(out))
+        except json.JSONDecodeError:
+            raise backend_error("unparseable bw get output")

agent_credential_broker/backends/openbao.py

@@ -0,0 +1,377 @@
+"""OpenBao (Vault-compatible) HTTP API backend -- stdlib only.
+
+Talks to the KV v2 engine at ``<openbao_mount>`` over plain
+``urllib.request``; there is no ``bao`` CLI dependency.
+
+    OpenBao --(HTTPS API)--> broker --> adapters
+
+Layout (design doc sections 3/4/6):
+
+    <mount>/data/<prefix>/<ref>      secret fields {username, password,
+                                     totp, uris, notes, ...}
+    <mount>/metadata/<prefix>/<ref>  custom_metadata: agent.* policy
+                                     fields + reserved ``label``/``uris``
+
+Key property: the ref index is built exclusively from the *metadata*
+endpoints -- ``data/*`` is only ever read by ``get_item`` on demand, so
+unlock + list_metadata move zero plaintext secrets through the broker.
+
+Authentication (non-interactive by design -- the ``password`` argument
+of ``unlock()`` is IGNORED for this backend; the 0600 credential files
+are the secret material, same model as client_id_file/client_secret_file):
+
+    1. AGENT_BROKER_OPENBAO_TOKEN (or the env var named by
+       ``openbao_token_env``)  -> verified via auth/token/lookup-self
+    2. openbao_token_file (0600) -> verified the same way
+    3. openbao_role_id_file + openbao_secret_id_file (0600)
+       -> POST /v1/auth/approle/login -> auth.client_token
+
+The token lives only in memory. Renewable tokens are renewed shortly
+before expiry; a 401/403 mid-session triggers one transparent AppRole
+re-login, then BROKER_LOCKED. lock()/logout() call
+auth/token/revoke-self and drop all in-memory material.
+
+Recommended AppRole policy (minimum):
+
+    path "<mount>/data/<prefix>/*"     { capabilities = ["read"] }
+    path "<mount>/metadata/<prefix>/*" { capabilities = ["read","list"] }
+"""
+
+from __future__ import annotations
+
+import http.client
+import json
+import os
+import ssl
+import time
+import urllib.error
+import urllib.request
+
+from .. import errors
+from ..config import read_secret_file
+from ..errors import BrokerError, backend_error
+from ..items import kv_metadata_projection, normalize_kv_item
+from ..sanitize import sanitize_text
+from . import VaultBackend
+
+_RENEW_MARGIN_S = 60        # renew a renewable token when <60s remain
+_LIST_MAX_DEPTH = 8         # guard for recursive metadata listing
+
+
+class _ApiError(Exception):
+    """Sanitized HTTP-layer failure (status + safe detail only)."""
+
+    def __init__(self, status: int, detail: str):
+        super().__init__(f"HTTP {status}: {detail}")
+        self.status = status
+        self.detail = detail
+
+
+class OpenBaoBackend(VaultBackend):
+    name = "openbao"
+
+    def __init__(self, config):
+        super().__init__(config)
+        self._addr = config.openbao_addr
+        self._mount = config.openbao_mount
+        self._prefix = config.openbao_prefix
+        self._timeout = config.request_timeout
+        self._max_bytes = config.max_response_bytes
+        self._token: str | None = None
+        self._token_expires_at: float | None = None
+        self._renewable = False
+        self._meta: list[dict] = []
+        # Live secrets, used ONLY to scrub error text before surfacing.
+        self._secrets: tuple = ()
+        self._ssl_ctx = self._build_ssl_ctx(config)
+
+    # -- plumbing ------------------------------------------------------
+
+    @staticmethod
+    def _build_ssl_ctx(config):
+        if not config.openbao_addr.startswith("https://"):
+            return None
+        if config.openbao_tls_skip_verify:
+            ctx = ssl.create_default_context()
+            ctx.check_hostname = False
+            ctx.verify_mode = ssl.CERT_NONE
+            return ctx
+        return ssl.create_default_context(cafile=config.openbao_ca_cert or None)
+
+    def _headers(self, token: str | None) -> dict:
+        h = {"Accept": "application/json"}
+        if token:
+            h["X-Vault-Token"] = token
+        if self.config.openbao_namespace:
+            h["X-Vault-Namespace"] = self.config.openbao_namespace
+        return h
+
+    def _san(self, text: str) -> str:
+        """Error text safe to surface: no token/role_id/secret_id echo."""
+        return sanitize_text(text or "", self._secrets).strip()[:300]
+
+    def _request(self, method: str, path: str, *, body=None,
+                 token: str | None = None) -> dict:
+        """One HTTP call. Returns parsed JSON on 2xx; raises _ApiError
+        on HTTP errors (sanitized) and VAULT_BACKEND_ERROR on transport
+        or parse failures. ``path`` may carry a query string."""
+        url = f"{self._addr}/v1/{path.lstrip('/')}"
+        data = None
+        headers = self._headers(token)
+        if body is not None:
+            data = json.dumps(body).encode()
+            headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(url, data=data, headers=headers,
+                                     method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout,
+                                        context=self._ssl_ctx) as resp:
+                status = resp.status
+                raw = resp.read(self._max_bytes + 1)
+        except urllib.error.HTTPError as e:
+            status = e.code
+            try:
+                raw = e.read(self._max_bytes + 1)
+            except OSError:
+                raw = b""
+        except (urllib.error.URLError, OSError, ValueError,
+                http.client.HTTPException) as e:
+            raise backend_error(
+                f"openbao request failed: {self._san(str(e)) or 'network error'}")
+        if len(raw) > self._max_bytes:
+            raise backend_error("openbao response exceeds max_response_bytes")
+        if status >= 400:
+            raise _ApiError(status, self._san(self._error_detail(raw)))
+        if not raw:
+            return {}
+        try:
+            parsed = json.loads(raw)
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            raise backend_error("unparseable openbao response")
+        if not isinstance(parsed, dict):
+            raise backend_error("unexpected openbao response shape")
+        return parsed
+
+    @staticmethod
+    def _error_detail(raw: bytes) -> str:
+        """Vault error bodies are {"errors": ["..."]}; fall back to the
+        (still sanitized) raw body when the shape differs."""
+        try:
+            errs = json.loads(raw).get("errors")
+            if isinstance(errs, list) and errs:
+                return "; ".join(str(x) for x in errs)
+        except Exception:
+            pass
+        return raw.decode("utf-8", "replace")
+
+    def _drop_token(self):
+        self._token = None
+        self._token_expires_at = None
+        self._renewable = False
+        self._secrets = ()
+        self._meta = []
+
+    # -- auth -----------------------------------------------------------
+
+    def _env_token(self) -> str | None:
+        return os.environ.get(self.config.openbao_token_env) or None
+
+    def _approle_available(self) -> bool:
+        c = self.config
+        return (c.openbao_role_id_file.exists()
+                and c.openbao_secret_id_file.exists())
+
+    def configured(self) -> bool:
+        c = self.config
+        return bool(self._env_token()
+                    or c.openbao_token_file.exists()
+                    or self._approle_available())
+
+    def _approle_login(self) -> None:
+        """POST auth/approle/login. 4xx -> UNLOCK_FAILED (bad/insufficient
+        credentials); anything else -> VAULT_BACKEND_ERROR."""
+        c = self.config
+        role_id = secret_id = None
+        try:
+            role_id = read_secret_file(c.openbao_role_id_file)
+            secret_id = read_secret_file(c.openbao_secret_id_file)
+            self._secrets = (role_id, secret_id)
+            resp = self._request(
+                "POST", "auth/approle/login",
+                body={"role_id": role_id, "secret_id": secret_id})
+        except _ApiError as e:
+            if 400 <= e.status < 500:
+                raise BrokerError(
+                    "UNLOCK_FAILED",
+                    f"openbao approle login failed ({e.status}): {e.detail}")
+            raise backend_error(f"openbao approle login failed ({e.status})")
+        finally:
+            role_id = secret_id = None
+        auth = resp.get("auth") or {}
+        token = auth.get("client_token")
+        if not token:
+            self._secrets = ()
+            raise backend_error("openbao approle login returned no client_token")
+        self._token = token
+        self._secrets = (token,)
+        self._renewable = bool(auth.get("renewable"))
+        lease = auth.get("lease_duration")
+        self._token_expires_at = (time.time() + float(lease)) if lease else None
+
+    def _token_file_or_env_login(self) -> bool:
+        """Direct token from env var or 0600 file -> verify with
+        auth/token/lookup-self. Returns False when no token source exists."""
+        c = self.config
+        token = self._env_token()
+        if not token and c.openbao_token_file.exists():
+            token = read_secret_file(c.openbao_token_file)
+        if not token:
+            return False
+        self._secrets = (token,)
+        try:
+            resp = self._request("GET", "auth/token/lookup-self", token=token)
+        except _ApiError as e:
+            self._secrets = ()
+            if 400 <= e.status < 500:
+                raise BrokerError(
+                    "UNLOCK_FAILED",
+                    f"openbao token rejected ({e.status}): {e.detail}")
+            raise backend_error(f"openbao token lookup failed ({e.status})")
+        data = resp.get("data") or {}
+        self._token = token
+        self._renewable = bool(data.get("renewable"))
+        ttl = data.get("ttl")
+        self._token_expires_at = (time.time() + float(ttl)) if ttl else None
+        return True
+
+    def _try_relogin(self) -> bool:
+        """One transparent AppRole re-login after a 401/403 (lazy
+        re-login, per design). Never raises."""
+        if not self._approle_available():
+            return False
+        try:
+            self._approle_login()
+            return True
+        except BrokerError:
+            return False
+
+    def _renew_token(self) -> None:
+        """renew-self before expiry. Auth failure drops the token ->
+        locked; transient failures keep the token for the next call."""
+        try:
+            resp = self._request("POST", "auth/token/renew-self",
+                                 token=self._token)
+        except _ApiError as e:
+            if e.status in (401, 403):
+                self._drop_token()
+                raise errors.locked()
+            raise backend_error(f"openbao token renew failed ({e.status})")
+        auth = resp.get("auth") or {}
+        lease = auth.get("lease_duration")
+        if lease:
+            self._token_expires_at = time.time() + float(lease)
+        self._renewable = bool(auth.get("renewable", self._renewable))
+
+    def _require_token(self) -> str:
+        if not self._token:
+            raise errors.locked()
+        if self._token_expires_at is not None:
+            remaining = self._token_expires_at - time.time()
+            if remaining <= 0:
+                self._drop_token()
+                raise errors.locked()
+            if self._renewable and remaining < _RENEW_MARGIN_S:
+                self._renew_token()
+        return self._token
+
+    def _authed(self, method: str, path: str, *, body=None,
+                allow_404: bool = False, _retry: bool = True):
+        """Authenticated API call with token lifecycle: renews near
+        expiry, re-logs once on 401/403 via AppRole, else locks."""
+        token = self._require_token()
+        try:
+            return self._request(method, path, body=body, token=token)
+        except _ApiError as e:
+            if e.status == 404 and allow_404:
+                return None
+            if e.status in (401, 403):
+                if _retry and self._try_relogin():
+                    return self._authed(method, path, body=body,
+                                        allow_404=allow_404, _retry=False)
+                self._drop_token()
+                raise errors.locked()
+            raise backend_error(
+                f"openbao {method} {path} failed ({e.status}): {e.detail}")
+
+    # -- VaultBackend ----------------------------------------------------
+
+    def unlock(self, password: str) -> None:
+        """Non-interactive by design: ``password`` is ignored (documented
+        in the module docstring -- the 0600 files are the credential)."""
+        self._drop_token()
+        if self._token_file_or_env_login():
+            pass
+        elif self._approle_available():
+            self._approle_login()
+        else:
+            raise errors.unconfigured(
+                "openbao: no token file/env and no approle credential files")
+        # Prefetch the ref index -- metadata endpoints only, never data/*.
+        self._refresh_meta()
+
+    def lock(self) -> None:
+        token, self._token = self._token, None
+        try:
+            if token:
+                self._request("POST", "auth/token/revoke-self", token=token)
+        except (BrokerError, _ApiError):
+            pass  # best-effort revoke; local state is dropped regardless
+        finally:
+            self._drop_token()
+
+    def logout(self) -> None:
+        """End the session exactly like lock(): revoke-self + drop."""
+        self.lock()
+
+    def list_metadata(self) -> list[dict]:
+        return self._meta
+
+    def _refresh_meta(self) -> None:
+        meta = []
+        for rel in self._list_keys(""):
+            resp = self._authed(
+                "GET", f"{self._mount}/metadata/{self._prefix}/{rel}",
+                allow_404=True)
+            cm = (((resp or {}).get("data") or {}).get("custom_metadata")) or {}
+            meta.append(kv_metadata_projection(rel, cm))
+        self._meta = meta
+
+    def _list_keys(self, sub: str, _depth: int = 0) -> list[str]:
+        """Recursive LIST over metadata/<prefix>/<sub>. Yields item ids
+        relative to the prefix (``foo`` / ``sub/foo``). 404 -> empty."""
+        if _depth > _LIST_MAX_DEPTH:
+            return []
+        rel = f"{self._prefix}/{sub}".rstrip("/")
+        resp = self._authed("GET", f"{self._mount}/metadata/{rel}?list=true",
+                            allow_404=True)
+        keys = ((resp or {}).get("data") or {}).get("keys") or []
+        out = []
+        for k in keys:
+            if not isinstance(k, str) or ".." in k:
+                continue
+            if k.endswith("/"):
+                out += self._list_keys(f"{sub}{k}", _depth + 1)
+            else:
+                out.append(f"{sub}{k}")
+        return out
+
+    def get_item(self, item_id: str) -> dict:
+        item_id = str(item_id or "")
+        if not item_id or ".." in item_id or item_id.startswith("/"):
+            raise errors.not_found(item_id)
+        resp = self._authed(
+            "GET", f"{self._mount}/data/{self._prefix}/{item_id}",
+            allow_404=True)
+        if resp is None:
+            raise errors.not_found(item_id)
+        return normalize_kv_item(item_id, resp.get("data") or {})

agent_credential_broker/cli.py

@@ -0,0 +1,118 @@
+"""agent-broker command line.
+
+    agent-broker daemon    run the unix-socket daemon (foreground)
+    agent-broker status
+    agent-broker unlock    interactive, TTY, no echo
+                                       (or non-interactive when
+                                       master_password_file is configured)
+    agent-broker lock
+    agent-broker confirm <ticket>
+
+The master password is read with getpass() by default -- it never arrives
+via argv or env. If config sets master_password_file, unlock reads it from
+that file instead (600 perms + same-owner enforced by read_secret_file).
+"""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import os
+import sys
+
+from . import __version__
+from .config import Config, read_secret_file, socket_path
+from .errors import BrokerError
+from .server import call, serve_forever
+
+
+def _out(obj):
+    print(json.dumps(obj, indent=2, sort_keys=True))
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="agent-broker")
+    ap.add_argument("--version", action="version", version=__version__)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("daemon", help="run the unix-socket daemon in the foreground")
+    sub.add_parser("status")
+    sub.add_parser("unlock", help="interactive unlock (TTY, no echo)")
+    sub.add_parser("lock")
+    sub.add_parser("logout", help="lock and log out the vault backend")
+    c = sub.add_parser("confirm", help="approve a pending confirmation ticket")
+    c.add_argument("ticket")
+    sub.add_parser("doctor", help="check installation prerequisites")
+    l = sub.add_parser("list-refs")
+    args = ap.parse_args(argv)
+
+    if args.cmd == "daemon":
+        serve_forever()
+        return 0
+    try:
+        if args.cmd == "status":
+            _out(call("status"))
+        elif args.cmd == "unlock":
+            mpf = Config.load().master_password_file
+            if mpf:
+                password = read_secret_file(mpf)
+            else:
+                if not (sys.stdin.isatty() and sys.stderr.isatty()):
+                    raise BrokerError("DENIED", "unlock requires an interactive TTY")
+                password = getpass.getpass("Master Password: ", stream=sys.stderr)
+            if not password:
+                raise BrokerError("DENIED", "empty password")
+            try:
+                _out(call("unlock", {"password": password}))
+            finally:
+                password = None
+        elif args.cmd == "lock":
+            _out(call("lock"))
+        elif args.cmd == "logout":
+            _out(call("logout"))
+        elif args.cmd == "confirm":
+            _out(call("confirm", {"ticket": args.ticket}))
+        elif args.cmd == "list-refs":
+            _out(call("list_refs"))
+        elif args.cmd == "doctor":
+            _out(doctor())
+    except BrokerError as e:
+        out = {"ok": False, "error": e.to_dict()}
+        if getattr(e, "ticket", None):
+            out["ticket"] = e.ticket
+        _out(out)
+        return 1
+    return 0
+
+
+def doctor():
+    cfg = Config.load()
+    import shutil
+    checks = {
+        "socket": str(socket_path()),
+        "vault_backend": cfg.vault_backend,
+        "agent_browser": bool(shutil.which("agent-browser")),
+        "git": bool(shutil.which("git")),
+        "ssh": bool(shutil.which("ssh")),
+        # bitwarden-cli backend
+        "vault_url": cfg.vault_url,
+        "bw": bool(shutil.which("bw") or (cfg.bw_path and os.path.exists(cfg.bw_path))),
+        "client_id_file": cfg.client_id_file.exists(),
+        "client_secret_file": cfg.client_secret_file.exists(),
+        # openbao backend
+        "openbao_addr": cfg.openbao_addr,
+        "openbao_role_id_file": cfg.openbao_role_id_file.exists(),
+        "openbao_secret_id_file": cfg.openbao_secret_id_file.exists(),
+        "openbao_token_file": cfg.openbao_token_file.exists(),
+        "openbao_token_env": bool(os.environ.get(cfg.openbao_token_env)),
+    }
+    try:
+        from .backends import make_backend
+        checks["configured"] = make_backend(cfg).configured()
+    except BrokerError:
+        checks["configured"] = False
+    return checks
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_credential_broker/config.py

@@ -0,0 +1,165 @@
+"""Broker configuration: files, paths and hardening defaults.
+
+No secret material ever lives in this module -- only *paths* to secret
+files and socket endpoints.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from pathlib import Path
+
+from .errors import BrokerError
+
+DEFAULT_VAULT_URL = "https://vault.paginica.com"
+
+CREDENTIALS_DIR = Path.home() / ".config" / "devin" / "credentials"
+CLIENT_ID_FILE = CREDENTIALS_DIR / "bitwarden-client-id.txt"
+CLIENT_SECRET_FILE = CREDENTIALS_DIR / "bitwarden-client-secret.token"
+
+# OpenBao defaults: loopback dev agent (see backlog 03); TLS via
+# openbao_ca_cert / openbao_tls_skip_verify when the listener is exposed.
+DEFAULT_OPENBAO_ADDR = "http://127.0.0.1:18200"
+OPENBAO_ROLE_ID_FILE = CREDENTIALS_DIR / "openbao-role-id.txt"
+OPENBAO_SECRET_ID_FILE = CREDENTIALS_DIR / "openbao-secret-id.txt"
+OPENBAO_TOKEN_FILE = CREDENTIALS_DIR / "openbao-token.txt"
+OPENBAO_TOKEN_ENV = "AGENT_BROKER_OPENBAO_TOKEN"
+
+
+def runtime_dir() -> Path:
+    base = os.environ.get("XDG_RUNTIME_DIR") or f"/run/user/{os.getuid()}"
+    p = Path(base) / "agent-broker"
+    p.mkdir(mode=0o700, parents=True, exist_ok=True)
+    os.chmod(p, 0o700)
+    return p
+
+
+def socket_path() -> Path:
+    return Path(os.environ.get("AGENT_BROKER_SOCKET", str(runtime_dir() / "broker.sock")))
+
+
+def state_dir() -> Path:
+    base = os.environ.get("XDG_STATE_HOME") or str(Path.home() / ".local" / "state")
+    p = Path(base) / "agent-broker"
+    p.mkdir(mode=0o700, parents=True, exist_ok=True)
+    os.chmod(p, 0o700)
+    return p
+
+
+def audit_log_path() -> Path:
+    p = state_dir() / "audit.jsonl"
+    if not p.exists():
+        p.touch(mode=0o600)
+    os.chmod(p, 0o600)
+    return p
+
+
+def tmp_dir() -> Path:
+    """Secret-bearing temp files live ONLY on the runtime tmpfs."""
+    p = runtime_dir() / "tmp"
+    p.mkdir(mode=0o700, parents=True, exist_ok=True)
+    os.chmod(p, 0o700)
+    return p
+
+
+def config_path() -> Path:
+    return Path(os.environ.get(
+        "AGENT_BROKER_CONFIG",
+        str(Path.home() / ".config" / "agent-broker" / "config.json"),
+    ))
+
+
+def profiles_dir() -> Path:
+    env = os.environ.get("AGENT_BROKER_PROFILES_DIR")
+    if env:
+        return Path(env)
+    default = Path(__file__).resolve().parent.parent / "profiles"
+    if default.is_dir():
+        return default
+    return Path.home() / ".config" / "agent-broker" / "profiles"
+
+
+class Config:
+    def __init__(self, data: dict):
+        self.vault_url = data.get("vault_url", DEFAULT_VAULT_URL).rstrip("/")
+        self.client_id_file = Path(data.get("client_id_file", str(CLIENT_ID_FILE)))
+        self.client_secret_file = Path(data.get("client_secret_file", str(CLIENT_SECRET_FILE)))
+        self.request_timeout = float(data.get("request_timeout", 15))
+        self.unlock_ttl_seconds = float(data.get("unlock_ttl_seconds", 3600))
+        self.confirmation_ttl_seconds = float(data.get("confirmation_ttl_seconds", 120))
+        self.max_response_bytes = int(data.get("max_response_bytes", 256 * 1024))
+        self.git_workdir_roots = data.get("git_workdir_roots", [])
+        # Optional non-interactive unlock: when set, `unlock` reads the
+        # master password from this file (same rules as credential files:
+        # 600 perms, owned by this user) instead of prompting via getpass.
+        self.master_password_file = (
+            Path(data["master_password_file"])
+            if data.get("master_password_file") else None
+        )
+        # Vault backend selection. "bitwarden-cli" (transition backend)
+        # and "openbao" are supported; anything else (including stale
+        # "legacy-crypto") fails loudly at daemon start -- no fallback.
+        self.vault_backend = data.get("vault_backend", "bitwarden-cli")
+        self.bw_path = data.get("bw_path")  # None -> PATH lookup
+        self.bw_appdata_dir = Path(data.get(
+            "bw_appdata_dir",
+            str(Path.home() / ".local" / "share" / "agent-broker"
+                / "bitwarden-cli")))
+
+        # --- OpenBao backend (vault_backend = "openbao") ---------------
+        # Items live at <mount>/data/<prefix>/<ref> (KV v2). Auth is
+        # non-interactive by design: an AppRole (role_id+secret_id read
+        # from 0600 files, same rules as client_id_file) or a direct
+        # token from a 0600 file / env var.
+        self.openbao_addr = data.get(
+            "openbao_addr", DEFAULT_OPENBAO_ADDR).rstrip("/")
+        self.openbao_mount = str(data.get("openbao_mount", "secret")).strip("/")
+        self.openbao_prefix = str(data.get("openbao_prefix", "agent")).strip("/")
+        # Optional namespace -> X-Vault-Namespace header on every request.
+        self.openbao_namespace = data.get("openbao_namespace") or None
+        # TLS: CA bundle path, or dev-only verification skip.
+        self.openbao_ca_cert = data.get("openbao_ca_cert") or None
+        self.openbao_tls_skip_verify = bool(
+            data.get("openbao_tls_skip_verify", False))
+        self.openbao_role_id_file = Path(data.get(
+            "openbao_role_id_file", str(OPENBAO_ROLE_ID_FILE)))
+        self.openbao_secret_id_file = Path(data.get(
+            "openbao_secret_id_file", str(OPENBAO_SECRET_ID_FILE)))
+        self.openbao_token_file = Path(data.get(
+            "openbao_token_file", str(OPENBAO_TOKEN_FILE)))
+        # Name of the env var holding a direct token (override with
+        # openbao_token_env; default AGENT_BROKER_OPENBAO_TOKEN).
+        self.openbao_token_env = data.get(
+            "openbao_token_env", OPENBAO_TOKEN_ENV) or OPENBAO_TOKEN_ENV
+
+    @classmethod
+    def load(cls) -> "Config":
+        path = config_path()
+        if path.exists():
+            try:
+                data = json.loads(path.read_text())
+            except Exception as e:
+                raise BrokerError("UNCONFIGURED", f"invalid config file {path}: {e}")
+            if not isinstance(data, dict):
+                raise BrokerError("UNCONFIGURED", f"invalid config file {path}")
+        else:
+            data = {}
+        return cls(data)
+
+
+def read_secret_file(path: Path) -> str:
+    """Read a local credential file for internal use only. Enforces that
+    the file is not group/other-readable."""
+    if not path.exists():
+        raise BrokerError("UNCONFIGURED", f"credential file not found: {path}")
+    st = path.stat()
+    if st.st_mode & (stat.S_IRWXG | stat.S_IRWXO):
+        raise BrokerError(
+            "UNCONFIGURED",
+            f"credential file {path} has unsafe permissions {oct(st.st_mode & 0o777)}; chmod 600",
+        )
+    if st.st_uid not in (os.getuid(), 0):
+        raise BrokerError("UNCONFIGURED", f"credential file {path} not owned by this user")
+    return path.read_text().strip()

agent_credential_broker/core.py

@@ -0,0 +1,256 @@
+"""Broker core: vault state, ref resolution, confirmations, dispatch.
+
+This object lives inside the daemon process and is the ONLY place where
+decrypted credential material exists -- in RAM, under a LOCKED default,
+auto-expiring after ``unlock_ttl_seconds``.
+"""
+
+from __future__ import annotations
+
+import secrets as _secrets
+import threading
+import time
+
+from . import errors, policy as pol
+from .audit import audit
+from .backends import make_backend
+from .config import Config
+from .items import wipe_item
+
+
+class VaultState:
+    def __init__(self):
+        self.items: list[dict] = []
+        self.ref_index: dict[str, list[int]] = {}
+        self.unlocked_at: float | None = None
+        self.session_approvals: set = set()
+        self.tickets: dict[str, dict] = {}
+
+    def clear(self):
+        for item in self.items:
+            for k, v in item.items():
+                item[k] = None
+        self.items = []
+        self.ref_index = {}
+        self.unlocked_at = None
+        self.session_approvals = set()
+        self.tickets = {}
+
+    @property
+    def unlocked(self) -> bool:
+        return self.unlocked_at is not None
+
+
+class BrokerCore:
+    def __init__(self, config: Config):
+        self.config = config
+        self.backend = make_backend(config)
+        self.state = VaultState()
+        self._lock = threading.RLock()
+
+    # -- lifecycle -----------------------------------------------------
+
+    def status(self) -> dict:
+        with self._lock:
+            self._expire_if_needed()
+            return {
+                "locked": not self.state.unlocked,
+                "configured": self._configured(),
+                "refs": len(self.state.ref_index) if self.state.unlocked else None,
+                "backend": self.backend.name,
+                "socket": "unix",
+            }
+
+    def _configured(self) -> bool:
+        return self.backend.configured()
+
+    def _expire_if_needed(self):
+        st = self.state
+        if st.unlocked and (time.time() - st.unlocked_at) > self.config.unlock_ttl_seconds:
+            st.clear()
+            self.backend.lock()
+            audit("auto_lock", result="ok", detail="ttl expired")
+
+    def unlock(self, password: str) -> dict:
+        if not self._configured():
+            raise errors.unconfigured()
+        try:
+            self.backend.unlock(password)
+        finally:
+            password = None
+        items = self.backend.list_metadata()
+        with self._lock:
+            self.state.clear()
+            self.state.items = items
+            for i, item in enumerate(items):
+                p = pol.policy_for(item)
+                if p:
+                    self.state.ref_index.setdefault(p.ref, []).append(i)
+            self.state.unlocked_at = time.time()
+            dupes = [r for r, idx in self.state.ref_index.items() if len(idx) > 1]
+            audit("unlock", result="ok", detail=f"items={len(items)} refs={len(self.state.ref_index)}")
+            return {
+                "unlocked": True,
+                "items": len(items),
+                "refs": len(self.state.ref_index),
+                "duplicate_refs": sorted(dupes),
+            }
+
+    def lock(self) -> dict:
+        with self._lock:
+            self.state.clear()
+            self.backend.lock()
+        audit("lock", result="ok")
+        return {"locked": True}
+
+    def logout(self) -> dict:
+        with self._lock:
+            self.state.clear()
+            self.backend.logout()
+        audit("logout", result="ok")
+        return {"locked": True, "logged_out": True}
+
+    # -- refs -----------------------------------------------------------
+
+    def _require_unlocked(self):
+        self._expire_if_needed()
+        if not self.state.unlocked:
+            raise errors.locked()
+
+    def _resolve_index(self, ref: str) -> int:
+        """Exact-match ref -> item index. 0 -> NOT_FOUND, >1 -> AMBIGUOUS_REF."""
+        idxs = self.state.ref_index.get(ref, [])
+        if not idxs:
+            raise errors.not_found(ref)
+        if len(idxs) > 1:
+            raise errors.ambiguous(ref, len(idxs))
+        return idxs[0]
+
+    def resolve_ref(self, ref: str) -> tuple[dict, pol.CredentialPolicy]:
+        """Internal resolve: returns (decrypted item, policy). Callers in
+        the process only -- the socket layer restricts who may receive
+        the secret material this yields."""
+        self._require_unlocked()
+        if not isinstance(ref, str) or not ref or len(ref) > 200:
+            raise errors.invalid_argument("bad ref")
+        item = self.state.items[self._resolve_index(ref)]
+        p = pol.policy_for(item)
+        if p is None:
+            raise errors.not_found(ref)
+        return item, p
+
+    def list_refs(self) -> list[dict]:
+        self._require_unlocked()
+        out = []
+        seen = set()
+        for ref, idxs in self.state.ref_index.items():
+            for i in idxs:
+                p = pol.policy_for(self.state.items[i])
+                meta = p.safe_metadata()
+                if len(idxs) > 1:
+                    meta["duplicate"] = True
+                if ref not in seen:
+                    out.append(meta)
+                    seen.add(ref)
+        return sorted(out, key=lambda m: m["ref"])
+
+    def find_for_url(self, url: str) -> list[str]:
+        self._require_unlocked()
+        refs = []
+        for ref in self.state.ref_index:
+            try:
+                item = self.state.items[self.state.ref_index[ref][0]]
+                p = pol.policy_for(item)
+                if p is None:
+                    continue
+                pol.require_url_allowed(p, url, require_https=False)
+                refs.append(ref)
+            except errors.BrokerError:
+                continue
+        return sorted(set(refs))
+
+    # -- confirmation ----------------------------------------------------
+
+    def _confirm(self, policy, adapter: str, target: str, ticket=None):
+        level = policy.confirmation
+        if level == "DENY":
+            raise errors.denied(f"credential {policy.ref!r} is DENY for confirmation")
+        if level == "AUTO":
+            return
+        if level == "SESSION" and (policy.ref, adapter) in self.state.session_approvals:
+            return
+        if ticket:
+            tk = self.state.tickets.pop(ticket, None)
+            if (tk and tk["approved"] and time.time() < tk["expires"]
+                    and tk["ref"] == policy.ref and tk["adapter"] == adapter):
+                if level == "SESSION":
+                    self.state.session_approvals.add((policy.ref, adapter))
+                return
+            raise errors.denied("confirmation ticket invalid or expired")
+        ticket_id = _secrets.token_urlsafe(24)
+        self.state.tickets[ticket_id] = {
+            "ref": policy.ref, "adapter": adapter, "target": target,
+            "approved": False, "expires": time.time() + self.config.confirmation_ttl_seconds,
+        }
+        audit("confirmation_pending", ref=policy.ref, adapter=adapter, target=target)
+        raise errors.confirmation_required(ticket_id)
+
+    def confirm(self, ticket: str) -> dict:
+        """Approve a pending ticket. Invoked interactively by the human."""
+        tk = self.state.tickets.get(ticket)
+        if not tk or time.time() > tk["expires"]:
+            raise errors.denied("unknown or expired ticket")
+        tk["approved"] = True
+        tk["expires"] = time.time() + self.config.confirmation_ttl_seconds
+        audit("confirmed", ref=tk["ref"], adapter=tk["adapter"], target=tk["target"])
+        return {"approved": True, "ref": tk["ref"], "adapter": tk["adapter"], "target": tk["target"]}
+
+    # -- adapter dispatch --------------------------------------------------
+
+    def run(self, adapter: str, params: dict) -> dict:
+        """Central guarded dispatch used by every adapter."""
+        self._require_unlocked()
+        ref = params.get("credential_ref") or params.get("ref")
+        ticket = params.get("ticket")
+        meta, p = self.resolve_ref(ref)
+        pol.require_adapter(p, adapter)
+        target = params.get("url") or params.get("host") or params.get("repository") or params.get("profile") or ""
+        from .adapters import registry
+        registry.validate(adapter, meta, p, params, self.config)
+        self._confirm(p, adapter, target, ticket=ticket)
+        item = self.backend.get_item(meta["id"])
+        try:
+            result = registry.run(adapter, item, p, params, self.config)
+            audit(adapter, ref=p.ref, adapter=adapter, target=target, result="ok")
+            return result
+        except errors.BrokerError as e:
+            audit(adapter, ref=p.ref, adapter=adapter, target=target, result="error", error_code=e.code)
+            raise
+        except Exception:
+            audit(adapter, ref=p.ref, adapter=adapter, target=target, result="error", error_code="INTERNAL_ERROR")
+            raise errors.internal("adapter failed")
+        finally:
+            wipe_item(item)
+
+    def resolve_for_plugin(self, ref: str, url: str | None) -> dict:
+        """Socket-exposed resolve for the agent-browser credential.read
+        plugin. Only usable for refs whose policy allows the browser
+        adapter; origin is validated when a URL is provided."""
+        meta, p = self.resolve_ref(ref)
+        pol.require_adapter(p, "browser")
+        if url:
+            pol.require_url_allowed(p, url)
+        audit("resolve", ref=p.ref, adapter="browser", target=url or p.uris[:1])
+        item = self.backend.get_item(meta["id"])
+        try:
+            secrets = {
+                "username": item.get("username"),
+                "password": item.get("password"),
+                "url": url or (p.uris[0] if p.uris else None),
+                "usernameSelector": p.username_selector,
+                "passwordSelector": p.password_selector,
+                "submitSelector": p.submit_selector,
+            }
+            return {k: v for k, v in secrets.items() if v}
+        finally:
+            wipe_item(item)

agent_credential_broker/errors.py

@@ -0,0 +1,76 @@
+"""Stable machine-readable error codes returned by the broker.
+
+Every failure crosses the socket/MCP boundary as {code, message} only --
+never with credential material attached.
+"""
+
+
+class BrokerError(Exception):
+    """Error that is safe to surface to the agent (no secret material)."""
+
+    def __init__(self, code, message):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+    def to_dict(self):
+        return {"code": self.code, "message": self.message}
+
+
+def locked():
+    return BrokerError("BROKER_LOCKED", "broker is locked; run 'agent-broker unlock'")
+
+
+def unconfigured(detail="missing API client credentials"):
+    return BrokerError(
+        "UNCONFIGURED",
+        f"broker not configured: {detail}",
+    )
+
+
+def not_found(ref):
+    return BrokerError("NOT_FOUND", f"no credential with ref {ref!r}")
+
+
+def ambiguous(ref, count):
+    return BrokerError("AMBIGUOUS_REF", f"ref {ref!r} matches {count} items; fix agent.ref duplicates")
+
+
+def adapter_denied(ref, adapter):
+    return BrokerError("ADAPTER_DENIED", f"credential {ref!r} is not allowed for adapter {adapter!r}")
+
+
+def origin_denied(ref, target):
+    return BrokerError("ORIGIN_DENIED", f"credential {ref!r} is not authorized for target {target!r}")
+
+
+def denied(message):
+    return BrokerError("DENIED", message)
+
+
+def invalid_argument(message):
+    return BrokerError("DENIED_INVALID_ARGUMENT", message)
+
+
+def confirmation_required(ticket=None):
+    err = BrokerError("CONFIRMATION_REQUIRED", "operation requires interactive confirmation")
+    err.ticket = ticket
+    return err
+
+
+def unsafe_tool_integration(tool):
+    return BrokerError(
+        "UNSAFE_TOOL_INTEGRATION",
+        f"{tool}: no credential-provider or safe injection path exists; refusing integration",
+    )
+
+
+def backend_error(message):
+    """Vault backend failure (e.g. `bw` subprocess). Never silently
+    falls back to another backend."""
+    return BrokerError("VAULT_BACKEND_ERROR", message)
+
+
+def internal(message):
+    """Server-side fault. Message must already be secret-free."""
+    return BrokerError("INTERNAL_ERROR", message)

agent_credential_broker/items.py

@@ -0,0 +1,172 @@
+"""Normalized vault item helpers shared by every vault backend.
+
+Internal item shape (produced by all backends)::
+
+    {id, type, name, username, password, totp, uris[], fields{name:value}, notes}
+
+``metadata_projection`` strips every secret-bearing field so the daemon
+can keep a searchable ref index without retaining decrypted credentials.
+``wipe_item`` drops secret values in place after a single use.
+"""
+
+from __future__ import annotations
+
+import json
+
+
+def normalize_bw_item(raw: dict) -> dict:
+    """Bitwarden CLI JSON item -> internal shape."""
+    login = raw.get("login") or {}
+    fields = {}
+    for f in raw.get("fields") or []:
+        name = f.get("name")
+        if name is not None:
+            fields[name] = f.get("value") if f.get("value") is not None else ""
+    uris = []
+    for u in login.get("uris") or []:
+        uri = u.get("uri")
+        if uri:
+            uris.append(uri)
+    return {
+        "id": raw.get("id"),
+        "type": raw.get("type"),
+        "name": raw.get("name"),
+        "username": login.get("username"),
+        "password": login.get("password"),
+        "totp": login.get("totp"),
+        "uris": uris,
+        "fields": fields,
+        "notes": raw.get("notes"),
+    }
+
+
+def _coerce_str(value) -> str:
+    """custom_metadata/field values are strings by contract; coerce
+    defensively so a structured value can never break the shape."""
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    return json.dumps(value, sort_keys=True)
+
+
+def _coerce_uris(raw) -> list[str]:
+    """URIs may be stored as a JSON list, a CSV string or a single
+    string (``data.uris`` / ``custom_metadata.uris`` in KV v2)."""
+    if not raw:
+        return []
+    if isinstance(raw, list):
+        return [str(u) for u in raw if u]
+    if isinstance(raw, str):
+        s = raw.strip()
+        if s.startswith("["):
+            try:
+                parsed = json.loads(s)
+            except json.JSONDecodeError:
+                parsed = None
+            if isinstance(parsed, list):
+                return [str(u) for u in parsed if u]
+        return [u.strip() for u in s.split(",") if u.strip()]
+    return []
+
+
+def normalize_kv_item(item_id: str, raw: dict) -> dict:
+    """OpenBao KV v2 read -> internal shape (mirror of normalize_bw_item).
+
+    ``raw`` is the ``data`` object of a ``<mount>/data/<path>`` read,
+    i.e. ``{"data": {...secret fields...}, "metadata": {...}}``.
+    ``item_id`` is the secret path relative to the configured prefix --
+    for OpenBao the id IS the path, so refs cannot collide by id.
+
+    Field mapping (design doc section 4): ``data.{username,password,
+    totp,uris,notes}`` are the secret-bearing fields; ``custom_metadata``
+    carries the ``agent.*`` policy fields plus reserved ``label``/``uris``
+    keys. Any other ``data.*`` or ``custom_metadata`` key lands in
+    ``fields`` exactly like a Bitwarden custom field.
+    """
+    data = (raw.get("data") or {}) if isinstance(raw, dict) else {}
+    meta = (raw.get("metadata") or {}) if isinstance(raw, dict) else {}
+    cm = meta.get("custom_metadata") or {}
+
+    fields = {}
+    for k, v in cm.items():
+        if k in ("label", "uris"):
+            continue  # reserved metadata keys, mapped below
+        fields[k] = _coerce_str(v)
+    for k, v in data.items():
+        if k in ("username", "password", "totp", "uris", "notes"):
+            continue
+        if k not in fields:
+            fields[k] = _coerce_str(v)
+
+    uris = _coerce_uris(data.get("uris")) or _coerce_uris(cm.get("uris"))
+    return {
+        "id": item_id,
+        "type": None,  # KV has no item type; nothing consumes it
+        "name": cm.get("label") or str(item_id).rsplit("/", 1)[-1],
+        "username": data.get("username"),
+        "password": data.get("password"),
+        "totp": data.get("totp"),
+        "uris": uris,
+        "fields": fields,
+        "notes": data.get("notes"),
+    }
+
+
+def kv_metadata_projection(item_id: str, custom_metadata: dict) -> dict:
+    """Ref-index entry built from KV ``custom_metadata`` ALONE -- the
+    metadata API never exposes ``data/*``, so the index can be built
+    without a single plaintext secret transiting the broker."""
+    cm = custom_metadata or {}
+    pseudo = {
+        "id": item_id,
+        "type": None,
+        "name": cm.get("label") or str(item_id).rsplit("/", 1)[-1],
+        "uris": _coerce_uris(cm.get("uris")),
+        "fields": {k: _coerce_str(v) for k, v in cm.items()},
+    }
+    return metadata_projection(pseudo)
+
+
+def metadata_projection(item: dict) -> dict:
+    """Copy carrying only what ref resolution and policy need -- every
+    secret-bearing value removed. ``fields`` keeps only ``agent.*``
+    policy metadata."""
+    return {
+        "id": item.get("id"),
+        "type": item.get("type"),
+        "name": item.get("name"),
+        "username": None,
+        "password": None,
+        "totp": None,
+        "uris": list(item.get("uris") or []),
+        "fields": {k: v for k, v in (item.get("fields") or {}).items()
+                   if k.startswith("agent.")},
+        "notes": None,
+    }
+
+
+def wipe_item(item: dict) -> None:
+    """Drop secret values in place after use."""
+    for k in ("password", "totp", "username", "notes"):
+        item[k] = None
+    fields = item.get("fields")
+    if isinstance(fields, dict):
+        for k in list(fields):
+            if not k.startswith("agent."):
+                fields[k] = None
+
+
+def item_secrets(item: dict) -> list[str]:
+    """All secret strings belonging to an item, for the output sanitizer."""
+    secrets = []
+    for key in ("password", "totp", "username", "notes"):
+        v = item.get(key)
+        if v and len(v) >= 4:
+            secrets.append(v)
+    for name, value in (item.get("fields") or {}).items():
+        if name.startswith("agent."):
+            continue  # policy metadata is not secret
+        if value and len(str(value)) >= 4:
+            secrets.append(str(value))
+    return secrets

agent_credential_broker/mcp_server.py

@@ -0,0 +1,228 @@
+"""MCP stdio server -- a thin, capability-only facade over the broker
+unix socket.
+
+Design rule: this process contains NO crypto and holds NO secret
+material. It only translates MCP tool calls into broker socket
+operations. By construction there is no get_password / get_secret /
+reveal / dump tool -- the tools below map to broker adapters that return
+sanitized metadata only.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from . import __version__
+from .errors import BrokerError
+from .server import call
+
+PROTOCOL_VERSION = "2024-11-05"
+SERVER_NAME = "agent-broker"
+
+
+def _str(name, desc, required=True):
+    p = {"type": "string", "description": desc}
+    return p, (required and [name] or [])
+
+
+def _obj(properties, required):
+    return {"type": "object", "properties": properties, "required": required,
+            "additionalProperties": False}
+
+
+TOOLS = [
+    {
+        "name": "vault_status",
+        "description": "Broker status: locked/unlocked, configured, ref count. No secrets.",
+        "inputSchema": _obj({}, []),
+        "_method": ("status", lambda a: {}),
+    },
+    {
+        "name": "vault_lock",
+        "description": "Lock the broker immediately (drops all in-memory credentials).",
+        "inputSchema": _obj({}, []),
+        "_method": ("lock", lambda a: {}),
+    },
+    {
+        "name": "vault_list_refs",
+        "description": "List credential references and safe metadata (never secret values).",
+        "inputSchema": _obj({}, []),
+        "_method": ("list_refs", lambda a: {}),
+    },
+    {
+        "name": "vault_find_for_url",
+        "description": "List credential refs whose policy allows the given URL.",
+        "inputSchema": _obj({"url": {"type": "string"}}, ["url"]),
+        "_method": ("find_for_url", lambda a: {"url": a["url"]}),
+    },
+    {
+        "name": "credential_http_request",
+        "description": "Run an HTTP request with a credential attached by the broker "
+                       "(bearer/basic per item policy). Returns sanitized response.",
+        "inputSchema": _obj({
+            "credential_ref": {"type": "string"},
+            "method": {"type": "string", "enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]},
+            "url": {"type": "string"},
+            "headers": {"type": "object"},
+            "body": {"type": "string"},
+            "follow_redirects": {"type": "boolean"},
+            "ticket": {"type": "string", "description": "confirmation ticket from a CONFIRMATION_REQUIRED response"},
+        }, ["credential_ref", "method", "url"]),
+        "_method": ("http_request", lambda a: a),
+    },
+    {
+        "name": "ssh_exec",
+        "description": "Run a single command over SSH using the credential's host policy. "
+                       "Private keys/passwords never leave the broker.",
+        "inputSchema": _obj({
+            "credential_ref": {"type": "string"},
+            "host": {"type": "string"},
+            "command": {"type": "string"},
+            "port": {"type": "integer"},
+            "ticket": {"type": "string"},
+        }, ["credential_ref", "host", "command"]),
+        "_method": ("ssh_exec", lambda a: a),
+    },
+    {
+        "name": "git_operation",
+        "description": "git clone/fetch/push using vault credentials via askpass. "
+                       "The credential never appears in the remote URL or argv.",
+        "inputSchema": _obj({
+            "credential_ref": {"type": "string"},
+            "op": {"type": "string", "enum": ["clone", "fetch", "push"]},
+            "repository": {"type": "string"},
+            "workdir": {"type": "string"},
+            "dest": {"type": "string"},
+            "remote": {"type": "string"},
+            "refspec": {"type": "string"},
+            "branch": {"type": "string"},
+            "ticket": {"type": "string"},
+        }, ["credential_ref", "op", "repository"]),
+        "_method": ("git_op", lambda a: a),
+    },
+    {
+        "name": "cli_run",
+        "description": "Run an allowlisted CLI profile with the credential injected by "
+                       "the broker (env/stdin/tmpfs-file). No arbitrary commands.",
+        "inputSchema": _obj({
+            "profile": {"type": "string"},
+            "credential_ref": {"type": "string"},
+            "args": {"type": "array", "items": {"type": "string"}},
+            "ticket": {"type": "string"},
+        }, ["profile", "credential_ref"]),
+        "_method": ("cli_run", lambda a: a),
+    },
+    {
+        "name": "browser_login",
+        "description": "Login to a site via agent-browser using the broker "
+                       "credential provider plugin. Secrets flow plugin->agent-browser, "
+                       "never through the agent.",
+        "inputSchema": _obj({
+            "credential_ref": {"type": "string"},
+            "url": {"type": "string"},
+            "session": {"type": "string"},
+            "username_selector": {"type": "string"},
+            "password_selector": {"type": "string"},
+            "submit_selector": {"type": "string"},
+            "ticket": {"type": "string"},
+        }, ["credential_ref"]),
+        "_method": ("browser_login", lambda a: a),
+    },
+    {
+        "name": "browser_fill_credential",
+        "description": "Fill username+password on the CURRENT page (no navigation) using "
+                       "the agent-browser credential provider and the item's allowed origin.",
+        "inputSchema": _obj({
+            "credential_ref": {"type": "string"},
+            "url": {"type": "string"},
+            "session": {"type": "string"},
+            "username_selector": {"type": "string"},
+            "password_selector": {"type": "string"},
+            "submit_selector": {"type": "string"},
+            "ticket": {"type": "string"},
+        }, ["credential_ref"]),
+        "_method": ("browser_fill_credential", lambda a: a),
+    },
+]
+
+# Hard guard: even a bug in the table above cannot create a secret-
+# retrieval tool -- the names are statically checked at startup.
+_FORBIDDEN = ("password", "secret", "token", "private_key", "reveal", "dump", "get_")
+for _t in TOOLS:
+    n = _t["name"].lower()
+    assert not any(b in n for b in _FORBIDDEN), f"forbidden tool name {n}"
+del _FORBIDDEN, _t, n
+
+
+def _result(obj):
+    return {"content": [{"type": "text", "text": json.dumps(obj, indent=2, sort_keys=True)}]}
+
+
+def _error_result(e: BrokerError):
+    out = {"error": e.to_dict()}
+    if getattr(e, "ticket", None):
+        out["ticket"] = e.ticket
+    return {"content": [{"type": "text", "text": json.dumps(out)}], "isError": True}
+
+
+def _handle(req: dict) -> dict | None:
+    method = req.get("method")
+    rid = req.get("id")
+    if method == "initialize":
+        return {"jsonrpc": "2.0", "id": rid, "result": {
+            "protocolVersion": PROTOCOL_VERSION,
+            "capabilities": {"tools": {}},
+            "serverInfo": {"name": SERVER_NAME, "version": __version__},
+        }}
+    if method == "notifications/initialized" or method == "notifications/cancelled":
+        return None
+    if method == "ping":
+        return {"jsonrpc": "2.0", "id": rid, "result": {}}
+    if method == "tools/list":
+        tools = [{k: v for k, v in t.items() if not k.startswith("_")} for t in TOOLS]
+        return {"jsonrpc": "2.0", "id": rid, "result": {"tools": tools}}
+    if method == "tools/call":
+        params = req.get("params") or {}
+        name = params.get("name")
+        args = params.get("arguments") or {}
+        tool = next((t for t in TOOLS if t["name"] == name), None)
+        if tool is None:
+            return {"jsonrpc": "2.0", "id": rid, "result":
+                    _error_result(BrokerError("DENIED", f"unknown tool {name!r}"))}
+        socket_method, mapper = tool["_method"]
+        try:
+            res = call(socket_method, mapper(args))
+            return {"jsonrpc": "2.0", "id": rid, "result": _result(res)}
+        except BrokerError as e:
+            return {"jsonrpc": "2.0", "id": rid, "result": _error_result(e)}
+    if rid is not None:
+        return {"jsonrpc": "2.0", "id": rid,
+                "error": {"code": -32601, "message": "method not found"}}
+    return None
+
+
+def main():
+    if sys.stdin.isatty():
+        print("agent-broker-mcp is the MCP stdio server — not a CLI.", file=sys.stderr)
+        print("For interactive commands use: agent-broker <status|unlock|lock|list-refs>", file=sys.stderr)
+        return 2
+    while True:
+        line = sys.stdin.readline()
+        if not line:
+            return 0
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            req = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        resp = _handle(req)
+        if resp is not None:
+            sys.stdout.write(json.dumps(resp) + "\n")
+            sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_credential_broker/plugin.py

@@ -0,0 +1,70 @@
+"""agent-browser ``credential.read`` plugin (agent-browser.plugin.v1).
+
+agent-browser writes ONE JSON envelope on stdin::
+
+    {"protocol": "agent-browser.plugin.v1",
+     "type": "credential.resolve",
+     "capability": "credential.read",
+     "request": {"profileName": "...", "itemRef": "...", "url": "..."}}
+
+and expects one JSON object on stdout::
+
+    {"protocol": "agent-browser.plugin.v1", "success": true,
+     "credential": {"username": ..., "password": ..., "url": ...,
+                    "usernameSelector": ..., "passwordSelector": ...,
+                    "submitSelector": ...}}
+
+The plugin is a thin proxy: it forwards (itemRef, url) to the broker over
+the unix socket and relays the credential. The broker enforces the
+item's adapter policy and origin validation before releasing anything.
+Secret values go agent-browser-stdin -> plugin -> agent-browser; the
+agent model never sees them.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from .errors import BrokerError
+from .server import call
+
+PROTOCOL = "agent-browser.plugin.v1"
+
+
+def _fail(message):
+    sys.stdout.write(json.dumps({
+        "protocol": PROTOCOL, "success": False, "error": str(message)[:300],
+    }) + "\n")
+
+
+def main():
+    try:
+        raw = sys.stdin.read(64 * 1024)
+        envelope = json.loads(raw)
+    except Exception:
+        _fail("bad plugin envelope")
+        return 1
+    if (envelope.get("protocol") != PROTOCOL
+            or envelope.get("type") != "credential.resolve"):
+        _fail("unsupported plugin request")
+        return 1
+    req = envelope.get("request") or {}
+    item_ref = req.get("itemRef")
+    url = req.get("url")
+    if not item_ref:
+        _fail("missing itemRef")
+        return 1
+    try:
+        cred = call("resolve", {"ref": item_ref, "url": url})
+    except BrokerError as e:
+        _fail(f"{e.code}: {e.message}")
+        return 0  # a clean denial is still a protocol-level response
+    sys.stdout.write(json.dumps({
+        "protocol": PROTOCOL, "success": True, "credential": cred,
+    }) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_credential_broker/policy.py

@@ -0,0 +1,167 @@
+"""Item-scoped policy derived from non-sensitive ``agent.*`` custom fields.
+
+Recognized fields (all optional except agent.ref):
+
+    agent.ref                 required. stable, unique, exact-match key
+    agent.adapters            csv whitelist, e.g. "browser,http,git"
+    agent.allowed_hosts       csv hostnames (ssh + host-level checks)
+    agent.allowed_urls        csv origins or origin+path prefixes
+    agent.auth_type           bearer | basic | none        (http)
+    agent.confirmation        AUTO | SESSION | EVERY_USE | DENY
+                              default: EVERY_USE (fail-safe)
+    agent.username_selector   browser field selector
+    agent.password_selector   browser field selector
+    agent.submit_selector     browser field selector
+    agent.ssh_user            ssh login override (else vault username)
+    agent.ssh_key_path        existing local key file to use instead of
+                              password auth (no key material moves)
+    agent.cli_profile         restrict this credential to one profile id
+    agent.insecure_http       "true" permits http:// targets (discouraged)
+
+Policy is enforced daemon-side. The agent never sees or controls it.
+"""
+
+from __future__ import annotations
+
+import urllib.parse
+from dataclasses import dataclass, field
+
+from .errors import adapter_denied, origin_denied, invalid_argument
+
+CONFIRMATION_LEVELS = {"AUTO", "SESSION", "EVERY_USE", "DENY"}
+
+SUPPORTED_ADAPTERS = {"browser", "http", "ssh", "git", "cli-profile"}
+
+
+def _csv(value: str | None) -> list[str]:
+    if not value:
+        return []
+    return [v.strip() for v in value.split(",") if v.strip()]
+
+
+def normalize_url(url: str) -> urllib.parse.ParseResult:
+    p = urllib.parse.urlparse(url if "://" in url else "https://" + url)
+    if p.scheme not in ("https", "http", "ssh", "git"):
+        raise invalid_argument(f"unsupported URL scheme {p.scheme!r}")
+    if not p.hostname:
+        raise invalid_argument(f"URL has no host: {url!r}")
+    return p
+
+
+def origin_of(url: str) -> str:
+    p = normalize_url(url)
+    port = f":{p.port}" if p.port else ""
+    return f"{p.scheme}://{p.hostname}{port}"
+
+
+@dataclass
+class CredentialPolicy:
+    ref: str
+    item_id: str
+    name: str = ""
+    adapters: set = field(default_factory=set)
+    allowed_hosts: set = field(default_factory=set)
+    allowed_urls: list = field(default_factory=list)
+    auth_type: str = "basic"
+    confirmation: str = "EVERY_USE"
+    username_selector: str | None = None
+    password_selector: str | None = None
+    submit_selector: str | None = None
+    ssh_user: str | None = None
+    ssh_key_path: str | None = None
+    cli_profile: str | None = None
+    insecure_http: bool = False
+    uris: list = field(default_factory=list)
+
+    def safe_metadata(self) -> dict:
+        """Metadata that is safe to show the agent (no values)."""
+        return {
+            "ref": self.ref,
+            "name": self.name,
+            "adapters": sorted(self.adapters),
+            "allowed_hosts": sorted(self.allowed_hosts),
+            "allowed_urls": list(self.allowed_urls),
+            "confirmation": self.confirmation,
+            "auth_type": self.auth_type,
+            "cli_profile": self.cli_profile,
+            "uris": list(self.uris),
+        }
+
+
+def _parse_allowed_url(raw: str) -> urllib.parse.ParseResult:
+    p = normalize_url(raw)
+    return p
+
+
+def policy_for(item: dict) -> CredentialPolicy | None:
+    fields = item.get("fields") or {}
+    ref = fields.get("agent.ref")
+    if not ref:
+        return None
+    adapters = {a for a in _csv(fields.get("agent.adapters"))}
+    unknown = adapters - SUPPORTED_ADAPTERS
+    if unknown:
+        adapters -= unknown
+    confirmation = (fields.get("agent.confirmation") or "EVERY_USE").upper()
+    if confirmation not in CONFIRMATION_LEVELS:
+        confirmation = "EVERY_USE"
+    auth_type = (fields.get("agent.auth_type") or "basic").lower()
+    if auth_type not in ("bearer", "basic", "none"):
+        auth_type = "basic"
+    allowed_urls = []
+    for raw in _csv(fields.get("agent.allowed_urls")) + list(item.get("uris") or []):
+        try:
+            p = _parse_allowed_url(raw)
+            allowed_urls.append(origin_of(raw) + (p.path.rstrip("/") or ""))
+        except Exception:
+            continue
+    return CredentialPolicy(
+        ref=ref.strip(),
+        item_id=item.get("id") or "",
+        name=item.get("name") or "",
+        adapters=adapters,
+        allowed_hosts={h.lower() for h in _csv(fields.get("agent.allowed_hosts"))},
+        allowed_urls=allowed_urls,
+        auth_type=auth_type,
+        confirmation=confirmation,
+        username_selector=fields.get("agent.username_selector"),
+        password_selector=fields.get("agent.password_selector"),
+        submit_selector=fields.get("agent.submit_selector"),
+        ssh_user=fields.get("agent.ssh_user"),
+        ssh_key_path=fields.get("agent.ssh_key_path"),
+        cli_profile=fields.get("agent.cli_profile"),
+        insecure_http=(fields.get("agent.insecure_http") or "").lower() == "true",
+        uris=list(item.get("uris") or []),
+    )
+
+
+def require_adapter(policy: CredentialPolicy, adapter: str):
+    if adapter not in policy.adapters:
+        raise adapter_denied(policy.ref, adapter)
+
+
+def _default_port(scheme: str) -> int:
+    return {"https": 443, "http": 80, "ssh": 22, "git": 9418}.get(scheme, -1)
+
+
+def require_url_allowed(policy: CredentialPolicy, url: str, *, require_https=True):
+    """Origin+path-prefix check against agent.allowed_urls / item URIs."""
+    p = normalize_url(url)
+    if require_https and p.scheme == "http" and not policy.insecure_http:
+        raise origin_denied(policy.ref, url)
+    cand_origin = f"{p.scheme}://{p.hostname}:{p.port or _default_port(p.scheme)}"
+    cand = cand_origin + (p.path.rstrip("/") or "")
+    for allowed in policy.allowed_urls:
+        ap = normalize_url(allowed)
+        a_origin = f"{ap.scheme}://{ap.hostname}:{ap.port or _default_port(ap.scheme)}"
+        if a_origin != cand_origin:
+            continue
+        a_path = ap.path.rstrip("/")
+        if not a_path or cand == a_origin + a_path or cand.startswith(a_origin + a_path + "/"):
+            return
+    raise origin_denied(policy.ref, url)
+
+
+def require_host_allowed(policy: CredentialPolicy, host: str):
+    if host.lower() not in policy.allowed_hosts:
+        raise origin_denied(policy.ref, host)

agent_credential_broker/sanitize.py

@@ -0,0 +1,71 @@
+"""Output sanitizer -- defence in depth.
+
+The *primary* guarantee is architectural: secret values never enter
+argv/stdout/stderr of adapter calls. This layer additionally scans any
+text crossing the broker boundary (child output, HTTP bodies/headers,
+exception text) and replaces occurrences of known secret material with
+[REDACTED]. If a secret appears in output, that is already an adapter
+bug -- the sanitizer makes sure it can never reach the agent.
+"""
+
+from __future__ import annotations
+
+import re
+
+REDACTED = "[REDACTED]"
+
+# Header names that must never be echoed back to the agent.
+SENSITIVE_HEADERS = {
+    "authorization",
+    "proxy-authorization",
+    "set-cookie",
+    "cookie",
+    "x-api-key",
+    "x-auth-token",
+    "x-csrf-token",
+    "x-session-token",
+    "www-authenticate",
+}
+
+# name=value / name: value patterns whose values are suppressed.
+_SECRET_KV = re.compile(
+    r"(?i)\b(password|passwd|pwd|secret|token|api[_-]?key|access[_-]?token|"
+    r"refresh[_-]?token|session[_-]?(id|token|key)|client[_-]?secret|"
+    r"private[_-]?key|authorization)\b(\s*[:=]\s*)(\"[^\"]*\"|'[^']*'|[^\s,;&}]{4,})"
+)
+
+_BEARER = re.compile(r"(?i)bearer\s+[A-Za-z0-9._~+/=-]{8,}")
+
+_CRED_IN_URL = re.compile(r"(https?|ssh|git)://[^/@\s]+(:[^/@\s]*)?@")
+
+
+def sanitize_text(text: str, secrets: list[str] | tuple[str, ...] = ()) -> str:
+    if not text:
+        return text
+    out = text
+    for secret in secrets:
+        if secret and len(secret) >= 4:
+            out = out.replace(secret, REDACTED)
+    out = _BEARER.sub("Bearer " + REDACTED, out)
+    out = _CRED_IN_URL.sub(r"\1://" + REDACTED + "@", out)
+    out = _SECRET_KV.sub(lambda m: m.group(1) + m.group(3) + REDACTED, out)
+    return out
+
+
+def sanitize_headers(headers: dict, secrets=()) -> dict:
+    """Return a copy of headers with sensitive entries dropped and
+    remaining values scrubbed for accidental secret content."""
+    out = {}
+    for k, v in headers.items():
+        if k.lower() in SENSITIVE_HEADERS:
+            out[k] = REDACTED
+        else:
+            out[k] = sanitize_text(str(v), secrets)
+    return out
+
+
+def sanitize_bytes(data: bytes, secrets: list[bytes] | tuple[bytes, ...] = ()) -> bytes:
+    for secret in secrets:
+        if secret:
+            data = data.replace(secret, REDACTED.encode())
+    return data

agent_credential_broker/server.py

@@ -0,0 +1,170 @@
+"""Unix-domain socket daemon. No TCP, ever.
+
+Socket: $XDG_RUNTIME_DIR/agent-broker/broker.sock (0600,
+dir 0700). Every request is one line of JSON:
+
+    {"method": "...", "params": {...}, "id": 1}
+
+Response:
+
+    {"ok": true, "result": {...}}
+    {"ok": false, "error": {"code": "...", "message": "..."}}
+
+The daemon additionally verifies the connecting peer UID via
+SO_PEERCRED -- only the owning user may talk to it.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import socketserver
+import struct
+import threading
+
+from .config import Config, socket_path
+from .core import BrokerCore
+from .errors import BrokerError, internal
+from .audit import audit
+
+_MAX_LINE = 1024 * 1024
+
+
+def _peer_uid(conn: socket.socket) -> int:
+    creds = conn.getsockopt(socket.SOL_SOCKET, socket.SO_PEERCRED, struct.calcsize("3i"))
+    _pid, uid, _gid = struct.unpack("3i", creds)
+    return uid
+
+
+class _Handler(socketserver.StreamRequestHandler):
+    def handle(self):
+        try:
+            if _peer_uid(self.request) != os.getuid():
+                self.wfile.write(b'{"ok":false,"error":{"code":"DENIED","message":"foreign uid"}}\n')
+                return
+        except OSError:
+            return
+        for raw in self.rfile:
+            if len(raw) > _MAX_LINE:
+                break
+            try:
+                req = json.loads(raw)
+            except json.JSONDecodeError:
+                self._send({"ok": False, "error": {"code": "DENIED_INVALID_ARGUMENT", "message": "bad json"}})
+                continue
+            self._send(self.server.dispatch(req))
+
+    def _send(self, obj):
+        try:
+            self.wfile.write(json.dumps(obj).encode() + b"\n")
+        except OSError:
+            pass
+
+
+class _Server(socketserver.ThreadingMixIn, socketserver.UnixStreamServer):
+    daemon_threads = True
+
+    def __init__(self, path: str, core: BrokerCore):
+        self.core = core
+        super().__init__(path, _Handler)
+
+    def dispatch(self, req: dict) -> dict:
+        if not isinstance(req, dict):
+            return _err(internal("bad request"))
+        method = req.get("method")
+        params = req.get("params") or {}
+        if not isinstance(params, dict):
+            return _err(BrokerError("DENIED_INVALID_ARGUMENT", "params must be an object"))
+        try:
+            result = self._route(method, params)
+            return {"ok": True, "result": result}
+        except BrokerError as e:
+            out = {"ok": False, "error": e.to_dict()}
+            if getattr(e, "ticket", None):
+                out["ticket"] = e.ticket
+            return out
+        except Exception:
+            return _err(internal("unexpected daemon error"))
+
+    def _route(self, method, params):
+        c = self.core
+        routes = {
+            "status": lambda: c.status(),
+            "unlock": lambda: c.unlock(params.get("password") or _bad("password required")),
+            "lock": lambda: c.lock(),
+            "logout": lambda: c.logout(),
+            "confirm": lambda: c.confirm(params.get("ticket") or _bad("ticket required")),
+            "list_refs": lambda: c.list_refs(),
+            "find_for_url": lambda: c.find_for_url(params.get("url") or _bad("url required")),
+            # internal path used by the agent-browser credential.read plugin
+            "resolve": lambda: c.resolve_for_plugin(
+                params.get("ref") or _bad("ref required"), params.get("url")),
+            "http_request": lambda: c.run("http", params),
+            "ssh_exec": lambda: c.run("ssh", params),
+            "git_op": lambda: c.run("git", params),
+            "cli_run": lambda: c.run("cli-profile", params),
+            "browser_login": lambda: c.run("browser", {**params, "op": "browser_login"}),
+            "browser_fill_credential": lambda: c.run("browser", {**params, "op": "browser_fill_credential"}),
+        }
+        fn = routes.get(method)
+        if fn is None:
+            raise BrokerError("DENIED_INVALID_ARGUMENT", f"unknown method {method!r}")
+        return fn()
+
+
+def _bad(msg):
+    raise BrokerError("DENIED_INVALID_ARGUMENT", msg)
+
+
+def _err(e: BrokerError) -> dict:
+    return {"ok": False, "error": e.to_dict()}
+
+
+def call(params_method: str, params: dict | None = None, *, timeout=60) -> dict:
+    """Client-side call into the daemon. Used by the CLI, the MCP server
+    and the agent-browser plugin."""
+    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    sock.settimeout(timeout)
+    try:
+        sock.connect(str(socket_path()))
+        sock.sendall(json.dumps({"method": params_method, "params": params or {}}).encode() + b"\n")
+        fh = sock.makefile("r")
+        line = fh.readline(_MAX_LINE)
+        if not line:
+            raise BrokerError("DAEMON_DOWN", "daemon closed connection")
+        resp = json.loads(line)
+    except (ConnectionRefusedError, FileNotFoundError, socket.timeout) as e:
+        raise BrokerError("DAEMON_DOWN", f"cannot reach broker daemon ({e.__class__.__name__}); is it running?")
+    finally:
+        sock.close()
+    if not resp.get("ok"):
+        err = resp.get("error") or {}
+        e = BrokerError(err.get("code", "INTERNAL_ERROR"), err.get("message", "unknown"))
+        if resp.get("ticket"):
+            e.ticket = resp["ticket"]
+        raise e
+    return resp.get("result")
+
+
+def serve_forever(config: Config | None = None):
+    config = config or Config.load()
+    path = socket_path()
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    try:
+        path.unlink()
+    except FileNotFoundError:
+        pass
+    core = BrokerCore(config)
+    server = _Server(str(path), core)
+    os.chmod(path, 0o600)
+    audit("daemon_start", result="ok", detail=str(path))
+    try:
+        server.serve_forever(poll_interval=0.5)
+    finally:
+        core.lock()
+        try:
+            path.unlink()
+        except OSError:
+            pass
+        audit("daemon_stop", result="ok")