Skip to content

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

Python
14.4 KB
Raw Blame
//! `graff keys`: sync provider logins between a person's own devices through
//! the end-to-end encrypted vault (harness ADR 0005, contract v1.1).
//!
//!   graff keys status [--json]        this device, its fingerprint, synced logins
//!   graff keys enable [--name N]      enroll this device (the first one creates the vault)
//!   graff keys devices [--json]       enrolled and pending devices
//!   graff keys approve <id> [--yes]   let a pending device read the vault
//!   graff keys remove <id> [--yes]    remove a device and rotate the vault key
//!   graff keys push|pull [provider]   graff's logins: codex, kimi, xai
//!   graff keys put|get <agent>/<slot> opaque bytes on stdin/stdout (for Harness)
//!
//! The bearer comes from HARNESS_BEARER; the edge from HARNESS_EDGE_URL.

const std = @import("std");
const builtin = @import("builtin");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const crypto = @import("vault_crypto.zig");
const client = @import("vault_client.zig");
const sync = @import("vault_sync.zig");
const keys_cli = @import("keys_cli.zig");
const credential_store = @import("credential_store.zig");
const oauth_helpers = @import("oauth_helpers.zig");

const device_account = "graff-vault-device";

pub const usage =
    \\usage: graff keys <status|enable|devices|approve|remove|push|pull|put|get> [options]
    \\  status [--json]                 this device, its fingerprint, and synced logins
    \\  enable [--name NAME]            enroll this device; the first device creates the vault
    \\  devices [--json]                enrolled and pending devices
    \\  approve <device-id> [--yes]     let a pending device read the vault
    \\  remove <device-id> [--yes]      remove a device and rotate the vault key
    \\  push [codex|kimi|xai]           upload graff's logins (all when omitted)
    \\  pull [codex|kimi|xai]           download graff's logins into their usual files
    \\  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.
    \\
;

/// graff's own provider logins and where graff keeps each one.
pub const Provider = struct { name: []const u8, kind: []const u8 };
pub const providers = [_]Provider{
    .{ .name = "codex", .kind = "rotating" },
    .{ .name = "kimi", .kind = "rotating" },
    .{ .name = "xai", .kind = "rotating" },
};

pub fn providerPath(arena: Allocator, home: []const u8, name: []const u8) ?[]const u8 {
    if (std.mem.eql(u8, name, "codex")) {
        const dir = oauth_helpers.codexHomeDir(arena, home) orelse return null;
        return oauth_helpers.codexAuthPath(arena, dir) catch null;
    }
    if (std.mem.eql(u8, name, "kimi")) return credential_store.oauthPath(arena, home, ".kimi");
    if (std.mem.eql(u8, name, "xai")) return credential_store.oauthPath(arena, home, ".xai");
    return null;
}

/// This device's id and key pair, created on first use. Stored as one
/// secret: the Keychain on macOS, the 0600 key file elsewhere.
pub const Identity = struct { id: []const u8, keys: crypto.DeviceKeys };

/// `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);
    const id = try std.fmt.allocPrint(arena, "dev-{s}", .{std.fmt.bytesToHex(raw, .lower)});
    const keys = crypto.DeviceKeys.generate(io);
    const secret = keys.encodeSecret();
    const value = try std.fmt.allocPrint(arena, "{s}:{s}", .{ id, &secret });
    if (!keys_cli.storeKey(io, gpa, arena, home, device_account, value)) return error.CannotStoreDeviceKey;
    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 };
}

/// Where the previous vault key waits during a rotation: beside the device
/// key file, or under ~/.graff.
pub fn prevKeyPath(arena: Allocator, home: []const u8, device_file: ?[]const u8) ![]const u8 {
    if (device_file) |f| if (std.fs.path.dirname(f)) |dir| return std.fmt.allocPrint(arena, "{s}/vault-prev-key", .{dir});
    return std.fmt.allocPrint(arena, "{s}/.graff/vault-prev-key", .{home});
}

const Opts = struct {
    action: []const u8 = "",
    arg: []const u8 = "",
    name: []const u8 = "",
    json: bool = false,
    yes: bool = false,
};

fn parse(args: []const []const u8) error{Usage}!Opts {
    var o: Opts = .{};
    var i: usize = 0;
    while (i < args.len) : (i += 1) {
        const a = args[i];
        if (std.mem.eql(u8, a, "--json")) {
            o.json = true;
        } else if (std.mem.eql(u8, a, "--yes") or std.mem.eql(u8, a, "-y")) {
            o.yes = true;
        } else if (std.mem.eql(u8, a, "--name")) {
            i += 1;
            if (i >= args.len) return error.Usage;
            o.name = args[i];
        } else if (std.mem.startsWith(u8, a, "--")) {
            return error.Usage;
        } else if (o.action.len == 0) {
            o.action = a;
        } else if (o.arg.len == 0) {
            o.arg = a;
        } else return error.Usage;
    }
    if (o.action.len == 0) return error.Usage;
    return o;
}

fn confirm(io: Io, out: *Io.Writer, question: []const u8) bool {
    out.print("{s} [y/N] ", .{question}) catch return false;
    out.flush() catch {};
    var buf: [64]u8 = undefined;
    var r = Io.File.stdin().reader(io, &buf);
    const line = r.interface.takeDelimiterExclusive('\n') catch return false;
    const t = std.mem.trim(u8, line, " \t\r");
    return t.len > 0 and (t[0] == 'y' or t[0] == 'Y');
}

/// Flush buffered output first: std.process.exit does not run defers.
fn exitFlushed(out: *Io.Writer, code: u8) noreturn {
    out.flush() catch {};
    std.process.exit(code);
}

fn splitItem(spec: []const u8) ?struct { agent: []const u8, slot: []const u8 } {
    const slash = std.mem.indexOfScalar(u8, spec, '/') orelse return null;
    if (slash == 0 or slash + 1 >= spec.len) return null;
    return .{ .agent = spec[0..slash], .slot = spec[slash + 1 ..] };
}

pub fn command(gpa: Allocator, io: Io, arena: Allocator, home: []const u8, env: anytype, args: []const []const u8) !void {
    var obuf: [4096]u8 = undefined;
    var w = Io.File.stdout().writerStreaming(io, &obuf);
    const out = &w.interface;
    defer out.flush() catch {};
    const o = parse(args) catch {
        try out.writeAll(usage);
        return;
    };
    const bearer = env.get("HARNESS_BEARER") orelse {
        try out.writeAll("graff keys: set HARNESS_BEARER (Harness passes it to graff)\n");
        exitFlushed(out, 2);
    };
    const creating = std.mem.eql(u8, o.action, "enable");
    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);
    };
    const edge_url = env.get("HARNESS_EDGE_URL") orelse client.default_edge;
    client.checkEdgeUrl(edge_url) catch {
        try out.print("graff keys: HARNESS_EDGE_URL must be https (plain http only to this machine): {s}\n", .{edge_url});
        exitFlushed(out, 2);
    };
    var http: client.Http = .{ .io = io, .gpa = gpa, .base = edge_url };
    var c: client.Client = .{ .io = io, .arena = arena, .transport = http.transport(), .bearer = bearer, .device_id = ident.id, .keys = ident.keys };
    var s = try sync.Session.open(io, arena, &c);
    s.prev_key_path = try prevKeyPath(arena, home, env.get("GRAFF_VAULT_DEVICE_FILE"));
    // Finish a rotation an earlier run was interrupted in.
    if (!creating) {
        if (Io.Dir.cwd().statFile(io, s.prev_key_path.?, .{})) |_| {
            s.migrate() catch |err| try out.print("note: finishing an interrupted key rotation failed ({t}); it will be retried\n", .{err});
        } else |_| {}
    }
    const fp = crypto.fingerprint(ident.keys.box.public_key);

    if (creating) {
        const name = if (o.name.len > 0) o.name else "graff device";
        switch (try s.enable(name)) {
            .enrolled => try out.print("✓ this device ({s}, fingerprint {s}) is enrolled\n", .{ ident.id, &fp }),
            .pending => try out.print("This device ({s}, fingerprint {s}) is waiting for approval.\nOn an enrolled device run: graff keys approve {s}\n", .{ ident.id, &fp, ident.id }),
        }
    } else if (std.mem.eql(u8, o.action, "status") or std.mem.eql(u8, o.action, "devices")) {
        const v = try c.getVault();
        if (o.json) {
            var js: std.json.Stringify = .{ .writer = out };
            try js.write(.{ .deviceId = ident.id, .fingerprint = &fp, .keyEpoch = v.keyEpoch, .devices = v.devices, .items = v.items });
            try out.writeAll("\n");
            return;
        }
        try out.print("this device: {s}  fingerprint {s}\n", .{ ident.id, &fp });
        for (v.devices) |d| {
            const dfp = s.deviceFingerprint(d) catch @as(crypto.Fingerprint, @splat('?'));
            try out.print("  {s:<10} {s}  {s}  {s}\n", .{ d.status, &dfp, d.deviceId, d.name });
        }
        if (std.mem.eql(u8, o.action, "status")) for (v.items) |it| {
            try out.print("  {s}/{s}  v{d}  {s}  {s}\n", .{ it.agent, it.slot, it.version, it.kind, it.status });
        };
    } else if (std.mem.eql(u8, o.action, "approve")) {
        const v = try c.getVault();
        const d = sync.Session.findDevice(v, o.arg) orelse {
            try out.print("no device {s} — see graff keys devices\n", .{o.arg});
            exitFlushed(out, 1);
        };
        const dfp = try s.deviceFingerprint(d);
        try out.print("Approve \"{s}\" ({s}), fingerprint {s}?\nCheck that fingerprint on that device with `graff keys status`.\n", .{ d.name, d.deviceId, &dfp });
        if (!o.yes and !confirm(io, out, "Approve")) {
            try out.writeAll("not approved\n");
            return;
        }
        try s.approve(o.arg);
        try out.print("✓ approved {s}\n", .{o.arg});
    } else if (std.mem.eql(u8, o.action, "remove")) {
        if (!o.yes and !confirm(io, out, "Remove this device and rotate the vault key?")) return;
        try s.remove(o.arg);
        try out.print("✓ removed {s} and rotated the vault key\n", .{o.arg});
    } else if (std.mem.eql(u8, o.action, "push") or std.mem.eql(u8, o.action, "pull")) {
        const pushing = o.action[1] == 'u' and o.action[2] == 's';
        for (providers) |p| {
            if (o.arg.len > 0 and !std.mem.eql(u8, o.arg, p.name)) continue;
            const path = providerPath(arena, home, p.name) orelse continue;
            if (pushing) {
                const bytes = Io.Dir.cwd().readFileAlloc(io, path, arena, .limited(1 << 20)) catch {
                    if (o.arg.len > 0) try out.print("  {s}: not signed in here\n", .{p.name});
                    continue;
                };
                const v = try s.push("graff", p.name, p.kind, bytes);
                try out.print("  ✓ {s} pushed (v{d})\n", .{ p.name, v });
            } else {
                const got = (try s.pull("graff", p.name)) orelse {
                    if (o.arg.len > 0) try out.print("  {s}: not in the vault\n", .{p.name});
                    continue;
                };
                try credential_store.replaceFile(io, Io.Dir.cwd(), path, got.bytes, credential_store.private_file);
                try out.print("  ✓ {s} pulled (v{d}) into {s}\n", .{ p.name, got.version, path });
            }
        }
    } else if (std.mem.eql(u8, o.action, "put") or std.mem.eql(u8, o.action, "get")) {
        const it = splitItem(o.arg) orelse {
            try out.writeAll("graff keys put|get needs <agent>/<slot>\n");
            exitFlushed(out, 2);
        };
        if (o.action[0] == 'p') {
            var ibuf: [4096]u8 = undefined;
            var r = Io.File.stdin().reader(io, &ibuf);
            const bytes = try r.interface.allocRemaining(arena, .limited(1 << 20));
            const v = try s.push(it.agent, it.slot, "static", bytes);
            try out.print("✓ stored {s}/{s} (v{d})\n", .{ it.agent, it.slot, v });
        } else {
            const got = (try s.pull(it.agent, it.slot)) orelse exitFlushed(out, 1);
            try out.writeAll(got.bytes);
        }
    } else {
        try out.writeAll(usage);
    }
}

test "splitItem and parse" {
    try std.testing.expectEqualStrings("claude", splitItem("claude/default").?.agent);
    try std.testing.expect(splitItem("noslash") == null);
    try std.testing.expect(splitItem("/x") == null);
    const o = try parse(&.{ "approve", "dev-1", "--yes" });
    try std.testing.expectEqualStrings("dev-1", o.arg);
    try std.testing.expect(o.yes);
    try std.testing.expectError(error.Usage, parse(&.{ "status", "--bogus" }));
}

test "providerPath maps graff's logins to their usual files" {
    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena_state.deinit();
    const a = arena_state.allocator();
    try std.testing.expect(std.mem.endsWith(u8, providerPath(a, "/h", "kimi").?, "/.kimi/credentials/graff-oauth.json"));
    try std.testing.expect(std.mem.endsWith(u8, providerPath(a, "/h", "xai").?, "/.xai/credentials/graff-oauth.json"));
    try std.testing.expect(providerPath(a, "/h", "zai") == null);
}