Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

graff keys: device key file for headless devices, and an HTTP end-to-end test

justrach8e5c44dac7f8
diff --git a/scripts/test-graff-keys-e2e.py b/scripts/test-graff-keys-e2e.py
new file mode 100755
index 00000000..20422cff
--- /dev/null
+++ b/scripts/test-graff-keys-e2e.py
@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""End-to-end `graff keys` over real HTTP: two devices, one local dev edge.
+
+Device A bootstraps the vault and pushes its xai login; device B enrolls,
+waits, gets approved, and pulls it; a forged signature is rejected; removing
+B rotates the key and A still reads everything.
+
+ python3 scripts/test-graff-keys-e2e.py [path/to/graff]
+"""
+import json, os, socket, subprocess, sys, tempfile, time
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+GRAFF = sys.argv[1] if len(sys.argv) > 1 else os.path.join(ROOT, "zig-out", "bin", "graff")
+
+
+def free_port():
+ s = socket.socket()
+ s.bind(("127.0.0.1", 0))
+ p = s.getsockname()[1]
+ s.close()
+ return p
+
+
+def main():
+ port = free_port()
+ edge = subprocess.Popen([sys.executable, os.path.join(ROOT, "scripts", "vault_edge_dev.py"), "--port", str(port)], stdout=subprocess.PIPE, text=True)
+ edge.stdout.readline()
+ tmp = tempfile.mkdtemp(prefix="graff-keys-e2e-")
+ try:
+ def dev(name):
+ home = os.path.join(tmp, name)
+ os.makedirs(os.path.join(home, ".xai", "credentials"), exist_ok=True)
+ env = {**os.environ, "HOME": home, "HARNESS_BEARER": "user1", "HARNESS_EDGE_URL": f"http://127.0.0.1:{port}", "GRAFF_VAULT_DEVICE_FILE": os.path.join(home, "device.key")}
+
+ def run(*args, stdin=None, ok=True):
+ r = subprocess.run([GRAFF, "keys", *args], env=env, input=stdin, capture_output=True, text=True, timeout=60)
+ if ok and r.returncode != 0:
+ raise SystemExit(f"FAIL graff keys {' '.join(args)} ({name}): exit {r.returncode}\n{r.stdout}{r.stderr}")
+ return r
+ return home, run
+
+ home_a, a = dev("a")
+ home_b, b = dev("b")
+ xai = os.path.join(home_a, ".xai", "credentials", "graff-oauth.json")
+ with open(xai, "w") as f:
+ json.dump({"access_token": "xai-access", "refresh_token": "xai-refresh", "expires_at": 1}, f)
+
+ assert "enrolled" in a("enable", "--name", "laptop").stdout, "A should bootstrap"
+ assert "pushed (v1)" in a("push", "xai").stdout
+ out = b("enable", "--name", "vps").stdout
+ assert "waiting for approval" in out, out
+ b_id = out.split("(")[1].split(",")[0]
+ denied = b("pull", "xai", ok=False)
+ assert denied.returncode != 0, "a pending device must not read the vault"
+ assert "✓ approved" in a("approve", b_id, "--yes").stdout
+ assert "pulled (v1)" in b("pull", "xai").stdout
+ pulled = os.path.join(home_b, ".xai", "credentials", "graff-oauth.json")
+ assert json.load(open(pulled))["refresh_token"] == "xai-refresh"
+ assert oct(os.stat(pulled).st_mode & 0o777) == "0o600", oct(os.stat(pulled).st_mode)
+ assert oct(os.stat(os.path.join(home_a, "device.key")).st_mode & 0o777) == "0o600"
+
+ assert "✓ stored claude/default" in a("put", "claude/default", stdin="opaque-bytes").stdout
+ assert b("get", "claude/default").stdout == "opaque-bytes"
+
+ # Forge: B's device id with a fresh key file must be refused.
+ forged = os.path.join(tmp, "forged.key")
+ with open(os.path.join(home_b, "device.key")) as f:
+ real = f.read().strip()
+ with open(os.path.join(home_a, "device.key")) as f:
+ other_secret = f.read().strip().split(":", 1)[1]
+ with open(forged, "w") as f:
+ f.write(real.split(":")[0] + ":" + other_secret)
+ env_f = {**os.environ, "HOME": home_b, "HARNESS_BEARER": "user1", "HARNESS_EDGE_URL": f"http://127.0.0.1:{port}", "GRAFF_VAULT_DEVICE_FILE": forged}
+ r = subprocess.run([GRAFF, "keys", "push", "xai"], env=env_f, capture_output=True, text=True, timeout=60)
+ assert r.returncode != 0, "a forged signature must be rejected"
+
+ assert "rotated the vault key" in a("remove", b_id, "--yes").stdout
+ status = json.loads(a("status", "--json").stdout)
+ assert status["keyEpoch"] == 2, status
+ assert "pulled" in a("pull", "xai").stdout
+ assert a("get", "claude/default").stdout == "opaque-bytes"
+ assert b("pull", "xai", ok=False).returncode != 0, "a removed device must not read the vault"
+ print("graff keys e2e: OK (bootstrap, approve, push/pull, put/get, forged signature, remove+rotate, 0600 files)")
+ finally:
+ edge.terminate()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/vault_edge_dev.py b/scripts/vault_edge_dev.py
new file mode 100755
index 00000000..7e962b8a
--- /dev/null
+++ b/scripts/vault_edge_dev.py
@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""Local reference edge for `graff keys` (harness ADR 0005, contract v1.1).
+
+Dev-mode auth like the Harness edge: the bearer is the user id. Mutating
+requests must carry a valid Ed25519 signature over
+`method|path|sha256hex(body)|tsMs|deviceId` from an enrolled device, within
+60 s and never replayed. Items are compare-and-swap on If-Match, leases block
+other writers, and PUTs must carry the current keyEpoch.
+
+ python3 scripts/vault_edge_dev.py --port 27641
+"""
+import argparse, base64, hashlib, json, threading, time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+LOCK = threading.Lock()
+VAULTS = {} # userId -> {"epoch", "devices": {id: dict}, "items": {"a/s": dict}}
+SEEN = set()
+
+
+def b64d(s):
+ return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+def vault(user):
+ return VAULTS.setdefault(user, {"epoch": 1, "devices": {}, "items": {}})
+
+
+class Edge(BaseHTTPRequestHandler):
+ def log_message(self, *a):
+ pass
+
+ def reply(self, status, obj=None):
+ body = b"" if obj is None else json.dumps(obj).encode()
+ self.send_response(status)
+ self.send_header("Content-Type", "application/json")
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ self.wfile.write(body)
+
+ def handle_any(self, method):
+ auth = self.headers.get("Authorization", "")
+ if not auth.startswith("Bearer ") or not auth[7:].strip():
+ return self.reply(401, {"error": "unauthorized"})
+ user = auth[7:].strip().split("@")[0]
+ body = self.rfile.read(int(self.headers.get("Content-Length") or 0))
+ data = json.loads(body) if body else {}
+ dev_id = self.headers.get("X-Vault-Device", "")
+ path = self.path
+ with LOCK:
+ v = vault(user)
+ registering = method == "POST" and path == "/vault/devices"
+ if method != "GET" and not registering and not self.verified(v, method, path, body, dev_id):
+ return self.reply(401, {"error": "bad_signature"})
+ return self.route(v, user, method, path, data, dev_id)
+
+ def verified(self, v, method, path, body, dev_id):
+ d = v["devices"].get(dev_id)
+ if not d or d["status"] != "enrolled":
+ return False
+ try:
+ ts = int(self.headers.get("X-Vault-Timestamp", ""))
+ sig = b64d(self.headers.get("X-Vault-Signature", ""))
+ except ValueError:
+ return False
+ if abs(time.time() * 1000 - ts) > 60_000 or (dev_id, ts, sig) in SEEN:
+ return False
+ msg = f"{method}|{path}|{hashlib.sha256(body).hexdigest()}|{ts}|{dev_id}".encode()
+ try:
+ Ed25519PublicKey.from_public_bytes(b64d(d["signingKey"])).verify(sig, msg)
+ except Exception:
+ return False
+ SEEN.add((dev_id, ts, sig))
+ return True
+
+ def route(self, v, user, method, path, data, dev_id):
+ devs, items = v["devices"], v["items"]
+ if method == "GET" and path == "/vault":
+ me = devs.get(dev_id, {})
+ heads = [{"agent": k.split("/")[0], "slot": k.split("/")[1], **{f: it[f] for f in ("version", "keyEpoch", "kind", "status")}, "leaseHolder": it.get("lease")} for k, it in items.items()]
+ pub = [{f: d[f] for f in ("deviceId", "name", "publicKey", "signingKey", "status")} for d in devs.values()]
+ return self.reply(200, {"userId": user, "keyEpoch": v["epoch"], "devices": pub, "wrappedKey": me.get("wrappedKey"), "items": heads})
+ if method == "POST" and path == "/vault/devices":
+ bootstrap = not any(d["status"] == "enrolled" for d in devs.values()) and data.get("wrappedKey")
+ devs[data["deviceId"]] = {**{f: data[f] for f in ("deviceId", "name", "publicKey", "signingKey")}, "status": "enrolled" if bootstrap else "pending", "wrappedKey": data.get("wrappedKey") if bootstrap else None}
+ return self.reply(200, {"status": devs[data["deviceId"]]["status"]})
+ if path.startswith("/vault/devices/"):
+ rest = path[len("/vault/devices/"):]
+ if rest.endswith("/approve"):
+ d = devs.get(rest[: -len("/approve")])
+ if not d:
+ return self.reply(404, {})
+ d.update(status="enrolled", wrappedKey=data["wrappedKey"])
+ return self.reply(200, {"status": "enrolled"})
+ if method == "DELETE":
+ devs.pop(rest, None)
+ return self.reply(204)
+ if path == "/vault/rotate":
+ enrolled = {i for i, d in devs.items() if d["status"] == "enrolled"}
+ if data.get("keyEpoch") != v["epoch"] + 1:
+ return self.reply(409, {"error": "stale_epoch"})
+ if set(data["wrappedKeys"]) != enrolled:
+ return self.reply(400, {"error": "wrappedKeys must cover exactly the enrolled devices"})
+ for i in enrolled:
+ devs[i]["wrappedKey"] = data["wrappedKeys"][i]
+ v["epoch"] = data["keyEpoch"]
+ return self.reply(200, {"keyEpoch": v["epoch"]})
+ if path.startswith("/vault/items/"):
+ parts = path[len("/vault/items/"):].split("/")
+ key, action = "/".join(parts[:2]), (parts[2] if len(parts) > 2 else "")
+ it = items.get(key)
+ if action == "lease":
+ it = items.setdefault(key, {"version": 0, "keyEpoch": v["epoch"], "kind": "rotating", "status": "ok"})
+ if method == "DELETE":
+ if it.get("lease") == dev_id:
+ it["lease"] = None
+ return self.reply(204)
+ if it.get("lease") not in (None, dev_id) and it.get("leaseUntil", 0) > time.time():
+ return self.reply(409, {"error": "lease_held"})
+ it.update(lease=dev_id, leaseUntil=time.time() + min(int(data.get("ttlSeconds", 60)), 60))
+ return self.reply(200, {"leaseHolder": dev_id})
+ if action == "status":
+ if not it:
+ return self.reply(404, {})
+ it["status"] = data["status"]
+ return self.reply(200, {"status": it["status"]})
+ if method == "GET":
+ if not it or it["version"] == 0:
+ return self.reply(404, {})
+ a, s = key.split("/")
+ return self.reply(200, {"agent": a, "slot": s, **{f: it[f] for f in ("version", "keyEpoch", "kind", "status", "nonce", "ciphertext")}})
+ if method == "PUT":
+ it = items.setdefault(key, {"version": 0, "keyEpoch": v["epoch"], "kind": data["kind"], "status": "ok"})
+ if it.get("lease") not in (None, dev_id) and it.get("leaseUntil", 0) > time.time():
+ return self.reply(409, {"error": "lease_held"})
+ if data.get("keyEpoch") != v["epoch"]:
+ return self.reply(409, {"error": "stale_epoch"})
+ if int(self.headers.get("If-Match", "-1")) != it["version"]:
+ return self.reply(412, {"currentVersion": it["version"]})
+ it.update(version=it["version"] + 1, keyEpoch=v["epoch"], **{f: data[f] for f in ("kind", "status", "nonce", "ciphertext")})
+ return self.reply(200, {"version": it["version"]})
+ return self.reply(404, {})
+
+ def do_GET(self):
+ self.handle_any("GET")
+
+ def do_POST(self):
+ self.handle_any("POST")
+
+ def do_PUT(self):
+ self.handle_any("PUT")
+
+ def do_DELETE(self):
+ self.handle_any("DELETE")
+
+
+if __name__ == "__main__":
+ ap = argparse.ArgumentParser()
+ ap.add_argument("--port", type=int, default=27641)
+ port = ap.parse_args().port
+ print(f"vault dev edge on http://127.0.0.1:{port}", flush=True)
+ ThreadingHTTPServer(("127.0.0.1", port), Edge).serve_forever()
diff --git a/src/keys_vault_cli.zig b/src/keys_vault_cli.zig
index 64bf45b3..8ec2a439 100644
--- a/src/keys_vault_cli.zig
+++ b/src/keys_vault_cli.zig
@@ -36,6 +36,7 @@ pub const usage =
\\ put <agent>/<slot> store stdin as an opaque item
\\ get <agent>/<slot> print an item's bytes
\\Needs HARNESS_BEARER (Harness passes it). HARNESS_EDGE_URL overrides the edge.
+ \\GRAFF_VAULT_DEVICE_FILE keeps this device's keys in a 0600 file instead of the Keychain.
\\
;
@@ -61,11 +62,11 @@ pub fn providerPath(arena: Allocator, home: []const u8, name: []const u8) ?[]con
/// secret: the Keychain on macOS, the 0600 key file elsewhere.
pub const Identity = struct { id: []const u8, keys: crypto.DeviceKeys };
-pub fn loadIdentity(io: Io, gpa: Allocator, arena: Allocator, home: []const u8, create: bool) !?Identity {
- if (keys_cli.loadStoredKey(io, arena, home, device_account)) |stored| {
- const colon = std.mem.indexOfScalar(u8, stored, ':') orelse return error.BadDeviceKey;
- return .{ .id = stored[0..colon], .keys = try crypto.DeviceKeys.decodeSecret(stored[colon + 1 ..]) };
- }
+/// `file`: GRAFF_VAULT_DEVICE_FILE — keep the identity in this 0600 file
+/// instead of the Keychain (headless servers, sandboxes, tests).
+pub fn loadIdentity(io: Io, gpa: Allocator, arena: Allocator, home: []const u8, create: bool, file: ?[]const u8) !?Identity {
+ if (file) |path| return loadIdentityFile(io, arena, path, create);
+ if (keys_cli.loadStoredKey(io, arena, home, device_account)) |stored| return try parseIdentity(stored);
if (!create) return null;
var raw: [16]u8 = undefined;
io.random(&raw);
@@ -77,6 +78,25 @@ pub fn loadIdentity(io: Io, gpa: Allocator, arena: Allocator, home: []const u8,
return .{ .id = id, .keys = keys };
}
+fn parseIdentity(stored: []const u8) !Identity {
+ const t = std.mem.trim(u8, stored, " \t\r\n");
+ const colon = std.mem.indexOfScalar(u8, t, ':') orelse return error.BadDeviceKey;
+ return .{ .id = t[0..colon], .keys = try crypto.DeviceKeys.decodeSecret(t[colon + 1 ..]) };
+}
+
+fn loadIdentityFile(io: Io, arena: Allocator, path: []const u8, create: bool) !?Identity {
+ if (Io.Dir.cwd().readFileAlloc(io, path, arena, .limited(4096))) |stored| return try parseIdentity(stored) else |_| {}
+ if (!create) return null;
+ var raw: [16]u8 = undefined;
+ io.random(&raw);
+ const id = try std.fmt.allocPrint(arena, "dev-{s}", .{std.fmt.bytesToHex(raw, .lower)});
+ const keys = crypto.DeviceKeys.generate(io);
+ const secret = keys.encodeSecret();
+ if (std.fs.path.dirname(path)) |dir| Io.Dir.cwd().createDirPath(io, dir) catch {};
+ try credential_store.replaceFile(io, Io.Dir.cwd(), path, try std.fmt.allocPrint(arena, "{s}:{s}\n", .{ id, &secret }), credential_store.private_file);
+ return .{ .id = id, .keys = keys };
+}
+
const Opts = struct {
action: []const u8 = "",
arg: []const u8 = "",
@@ -146,7 +166,7 @@ pub fn command(gpa: Allocator, io: Io, arena: Allocator, home: []const u8, env:
exitFlushed(out, 2);
};
const creating = std.mem.eql(u8, o.action, "enable");
- const ident = (try loadIdentity(io, gpa, arena, home, creating)) orelse {
+ const ident = (try loadIdentity(io, gpa, arena, home, creating, env.get("GRAFF_VAULT_DEVICE_FILE"))) orelse {
try out.writeAll("This device is not enrolled. Run `graff keys enable` first.\n");
exitFlushed(out, 2);
};