Skip to content

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

Python
13.1 KB
Raw Blame
//! End-to-end crypto for the login vault (harness ADR 0005, contract v1.1).
//! The edge only ever sees public keys, wrapped keys, and ciphertext.
//!
//! - Device keys: X25519 (key wrapping) + Ed25519 (request signing).
//! - Vault key: 32 random bytes, created by the first device.
//! - Wrap: ephemeral X25519 to the recipient's public key → HKDF-SHA256
//!   (salt = ephPub‖recipientPub, info = "harness-vault-v1 wrap") →
//!   XChaCha20-Poly1305, random 24-byte nonce,
//!   aad = "wrap|userId|deviceId|keyEpoch" (so an old epoch cannot be replayed).
//!   wrappedKey = ephPub ‖ nonce ‖ ciphertext ‖ tag.
//! - Item: XChaCha20-Poly1305 under the vault key, random nonce,
//!   aad = "userId|agent|slot|version|keyEpoch"; stored as ciphertext ‖ tag.
//! - Requests: Ed25519 over "method|path|sha256hex(body)|timestampMs|deviceId".

const std = @import("std");
const Io = std.Io;
const Allocator = std.mem.Allocator;

const X25519 = std.crypto.dh.X25519;
const Ed25519 = std.crypto.sign.Ed25519;
const Aead = std.crypto.aead.chacha_poly.XChaCha20Poly1305;
const Hkdf = std.crypto.kdf.hkdf.HkdfSha256;
const Sha256 = std.crypto.hash.sha2.Sha256;
const b64 = std.base64.url_safe_no_pad;

pub const key_len = 32;
pub const nonce_len = Aead.nonce_length;
pub const tag_len = Aead.tag_length;
pub const wrapped_len = X25519.public_length + nonce_len + key_len + tag_len;
const wrap_info = "harness-vault-v1 wrap";

pub const VaultKey = [key_len]u8;

pub const DeviceKeys = struct {
    box: X25519.KeyPair,
    sign: Ed25519.KeyPair,

    pub fn generate(io: Io) DeviceKeys {
        return .{ .box = X25519.KeyPair.generate(io), .sign = Ed25519.KeyPair.generate(io) };
    }

    /// Both secrets as one hex string, for the Keychain or a 0600 file.
    pub fn encodeSecret(k: DeviceKeys) [2 * (X25519.secret_length + Ed25519.KeyPair.seed_length)]u8 {
        var raw: [X25519.secret_length + Ed25519.KeyPair.seed_length]u8 = undefined;
        @memcpy(raw[0..X25519.secret_length], &k.box.secret_key);
        @memcpy(raw[X25519.secret_length..], &k.sign.secret_key.seed());
        return std.fmt.bytesToHex(raw, .lower);
    }

    pub fn decodeSecret(hex: []const u8) !DeviceKeys {
        var raw: [X25519.secret_length + Ed25519.KeyPair.seed_length]u8 = undefined;
        if (hex.len != raw.len * 2) return error.BadDeviceKey;
        _ = std.fmt.hexToBytes(&raw, hex) catch return error.BadDeviceKey;
        const box_secret = raw[0..X25519.secret_length].*;
        const seed = raw[X25519.secret_length..].*;
        return .{
            .box = .{ .secret_key = box_secret, .public_key = X25519.recoverPublicKey(box_secret) },
            .sign = try Ed25519.KeyPair.generateDeterministic(seed),
        };
    }
};

pub const fingerprint_hex = 20;
/// Display width: 20 hex chars in groups of 4.
pub const Fingerprint = [fingerprint_hex + fingerprint_hex / 4 - 1]u8;

/// First 80 bits of sha256(X25519 public key), as "abcd ef01 2345 6789 abcd":
/// what `approve` asks the user to compare and `status` prints. 80 bits so a
/// bearer holder cannot grind a look-alike device key.
pub fn fingerprint(box_public: [X25519.public_length]u8) Fingerprint {
    var digest: [Sha256.digest_length]u8 = undefined;
    Sha256.hash(&box_public, &digest, .{});
    const hex = std.fmt.bytesToHex(digest, .lower);
    var out: Fingerprint = undefined;
    var o: usize = 0;
    for (hex[0..fingerprint_hex], 0..) |ch, i| {
        if (i > 0 and i % 4 == 0) {
            out[o] = ' ';
            o += 1;
        }
        out[o] = ch;
        o += 1;
    }
    return out;
}

fn wrapAad(buf: []u8, user_id: []const u8, device_id: []const u8, key_epoch: u64) ![]const u8 {
    return std.fmt.bufPrint(buf, "wrap|{s}|{s}|{d}", .{ user_id, device_id, key_epoch });
}

fn wrapKeyFor(shared: [X25519.shared_length]u8, eph_pub: [32]u8, recipient_pub: [32]u8) [key_len]u8 {
    var salt: [64]u8 = undefined;
    @memcpy(salt[0..32], &eph_pub);
    @memcpy(salt[32..], &recipient_pub);
    const prk = Hkdf.extract(&salt, &shared);
    var out: [key_len]u8 = undefined;
    Hkdf.expand(&out, wrap_info, prk);
    return out;
}

/// Wrap the vault key to one device's X25519 public key.
pub fn wrap(io: Io, vault_key: VaultKey, recipient_pub: [32]u8, user_id: []const u8, device_id: []const u8, key_epoch: u64) ![wrapped_len]u8 {
    const eph = X25519.KeyPair.generate(io);
    const shared = try X25519.scalarmult(eph.secret_key, recipient_pub);
    const k = wrapKeyFor(shared, eph.public_key, recipient_pub);
    var out: [wrapped_len]u8 = undefined;
    @memcpy(out[0..32], &eph.public_key);
    const nonce = out[32..][0..nonce_len];
    io.random(nonce);
    var abuf: [512]u8 = undefined;
    const aad = try wrapAad(&abuf, user_id, device_id, key_epoch);
    const ct = out[32 + nonce_len ..][0..key_len];
    const tag = out[32 + nonce_len + key_len ..][0..tag_len];
    Aead.encrypt(ct, tag, &vault_key, aad, nonce.*, k);
    return out;
}

/// `key_epoch` is the epoch GET /vault reports; a wrapped key from another
/// epoch fails to open.
pub fn unwrap(keys: DeviceKeys, wrapped: []const u8, user_id: []const u8, device_id: []const u8, key_epoch: u64) !VaultKey {
    if (wrapped.len != wrapped_len) return error.BadWrappedKey;
    const eph_pub = wrapped[0..32].*;
    const shared = try X25519.scalarmult(keys.box.secret_key, eph_pub);
    const k = wrapKeyFor(shared, eph_pub, keys.box.public_key);
    var abuf: [512]u8 = undefined;
    const aad = try wrapAad(&abuf, user_id, device_id, key_epoch);
    var out: VaultKey = undefined;
    const nonce = wrapped[32..][0..nonce_len].*;
    const ct = wrapped[32 + nonce_len ..][0..key_len];
    const tag = wrapped[32 + nonce_len + key_len ..][0..tag_len].*;
    Aead.decrypt(&out, ct, tag, aad, nonce, k) catch return error.WrongKeyOrTampered;
    return out;
}

pub const ItemRef = struct {
    user_id: []const u8,
    agent: []const u8,
    slot: []const u8,
    version: u64,
    key_epoch: u64,
};

fn itemAad(arena: Allocator, r: ItemRef) ![]const u8 {
    return std.fmt.allocPrint(arena, "{s}|{s}|{s}|{d}|{d}", .{ r.user_id, r.agent, r.slot, r.version, r.key_epoch });
}

pub const Sealed = struct {
    nonce: [nonce_len]u8,
    /// ciphertext ‖ tag
    body: []u8,
};

pub fn seal(io: Io, arena: Allocator, vault_key: VaultKey, r: ItemRef, plaintext: []const u8) !Sealed {
    var s: Sealed = .{ .nonce = undefined, .body = try arena.alloc(u8, plaintext.len + tag_len) };
    io.random(&s.nonce);
    Aead.encrypt(s.body[0..plaintext.len], s.body[plaintext.len..][0..tag_len], plaintext, try itemAad(arena, r), s.nonce, vault_key);
    return s;
}

pub fn open(arena: Allocator, vault_key: VaultKey, r: ItemRef, nonce: []const u8, body: []const u8) ![]u8 {
    if (nonce.len != nonce_len or body.len < tag_len) return error.WrongKeyOrTampered;
    const n = body.len - tag_len;
    const out = try arena.alloc(u8, n);
    Aead.decrypt(out, body[0..n], body[n..][0..tag_len].*, try itemAad(arena, r), nonce[0..nonce_len].*, vault_key) catch return error.WrongKeyOrTampered;
    return out;
}

/// The string a mutating request signs. The body hash is always sha256 hex,
/// including for an empty body.
pub fn signingString(arena: Allocator, method: []const u8, path: []const u8, body: []const u8, ts_ms: i64, device_id: []const u8) ![]const u8 {
    var d: [Sha256.digest_length]u8 = undefined;
    Sha256.hash(body, &d, .{});
    const hex = std.fmt.bytesToHex(d, .lower);
    return std.fmt.allocPrint(arena, "{s}|{s}|{s}|{d}|{s}", .{ method, path, &hex, ts_ms, device_id });
}

/// base64url Ed25519 signature for X-Vault-Signature.
pub fn signRequest(arena: Allocator, keys: DeviceKeys, method: []const u8, path: []const u8, body: []const u8, ts_ms: i64, device_id: []const u8) ![]const u8 {
    const msg = try signingString(arena, method, path, body, ts_ms, device_id);
    const sig = try keys.sign.sign(msg, null);
    return encode(arena, &sig.toBytes());
}

pub fn encode(arena: Allocator, bytes: []const u8) ![]const u8 {
    const out = try arena.alloc(u8, b64.Encoder.calcSize(bytes.len));
    return b64.Encoder.encode(out, bytes);
}

pub fn decode(arena: Allocator, text: []const u8) ![]u8 {
    const n = b64.Decoder.calcSizeForSlice(text) catch return error.BadBase64;
    const out = try arena.alloc(u8, n);
    b64.Decoder.decode(out, text) catch return error.BadBase64;
    return out;
}

/// The Harness bearer is a JWT whose `sub` is the user id. graff only reads
/// it; the edge verifies it. A dev-mode bearer is `user` or `user@org`.
pub fn userIdFromBearer(arena: Allocator, bearer: []const u8) ![]const u8 {
    var parts = std.mem.splitScalar(u8, bearer, '.');
    _ = parts.next();
    const payload = parts.next() orelse {
        const at = std.mem.indexOfScalar(u8, bearer, '@') orelse bearer.len;
        if (at == 0) return error.BadBearer;
        return bearer[0..at];
    };
    const json = try decode(arena, payload);
    const v = std.json.parseFromSliceLeaky(std.json.Value, arena, json, .{}) catch return error.BadBearer;
    if (v != .object) return error.BadBearer;
    const sub = v.object.get("sub") orelse return error.BadBearer;
    if (sub != .string or sub.string.len == 0) return error.BadBearer;
    return sub.string;
}

test "wrap/unwrap round-trips to the right device and rejects the wrong aad or device" {
    const io = std.testing.io;
    const a = DeviceKeys.generate(io);
    const b = DeviceKeys.generate(io);
    var vk: VaultKey = undefined;
    io.random(&vk);
    const w = try wrap(io, vk, a.box.public_key, "u1", "dev-a", 3);
    try std.testing.expectEqualSlices(u8, &vk, &(try unwrap(a, &w, "u1", "dev-a", 3)));
    try std.testing.expectError(error.WrongKeyOrTampered, unwrap(a, &w, "u2", "dev-a", 3));
    try std.testing.expectError(error.WrongKeyOrTampered, unwrap(a, &w, "u1", "dev-b", 3));
    try std.testing.expectError(error.WrongKeyOrTampered, unwrap(b, &w, "u1", "dev-a", 3));
    // An edge replaying an older epoch's wrapped key is caught.
    try std.testing.expectError(error.WrongKeyOrTampered, unwrap(a, &w, "u1", "dev-a", 4));
}

test "item seal/open round-trips and any aad field change is rejected" {
    const io = std.testing.io;
    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena_state.deinit();
    const arena = arena_state.allocator();
    var vk: VaultKey = undefined;
    io.random(&vk);
    const r: ItemRef = .{ .user_id = "u1", .agent = "graff", .slot = "codex", .version = 3, .key_epoch = 1 };
    const s = try seal(io, arena, vk, r, "{\"refresh\":\"secret\"}");
    try std.testing.expectEqualStrings("{\"refresh\":\"secret\"}", try open(arena, vk, r, &s.nonce, s.body));
    var bad = r;
    bad.version = 4;
    try std.testing.expectError(error.WrongKeyOrTampered, open(arena, vk, bad, &s.nonce, s.body));
    bad = r;
    bad.key_epoch = 2;
    try std.testing.expectError(error.WrongKeyOrTampered, open(arena, vk, bad, &s.nonce, s.body));
    bad = r;
    bad.slot = "kimi";
    try std.testing.expectError(error.WrongKeyOrTampered, open(arena, vk, bad, &s.nonce, s.body));
    s.body[0] ^= 1;
    try std.testing.expectError(error.WrongKeyOrTampered, open(arena, vk, r, &s.nonce, s.body));
}

test "device secret survives encode/decode and request signatures verify" {
    const io = std.testing.io;
    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena_state.deinit();
    const arena = arena_state.allocator();
    const k = DeviceKeys.generate(io);
    const back = try DeviceKeys.decodeSecret(&k.encodeSecret());
    try std.testing.expectEqualSlices(u8, &k.box.public_key, &back.box.public_key);
    try std.testing.expectEqualSlices(u8, &k.sign.public_key.toBytes(), &back.sign.public_key.toBytes());
    const sig_b64 = try signRequest(arena, back, "PUT", "/vault/items/graff/codex", "{}", 1700000000000, "dev-a");
    const sig = Ed25519.Signature.fromBytes((try decode(arena, sig_b64))[0..64].*);
    try sig.verify(try signingString(arena, "PUT", "/vault/items/graff/codex", "{}", 1700000000000, "dev-a"), k.sign.public_key);
    try std.testing.expectError(error.SignatureVerificationFailed, sig.verify(try signingString(arena, "PUT", "/vault/items/graff/kimi", "{}", 1700000000000, "dev-a"), k.sign.public_key));
    try std.testing.expectEqualStrings("DELETE|/vault/devices/x|e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855|5|d", try signingString(arena, "DELETE", "/vault/devices/x", "", 5, "d"));
}

test "userIdFromBearer reads the JWT sub and the dev forms" {
    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena_state.deinit();
    const arena = arena_state.allocator();
    const payload = try encode(arena, "{\"sub\":\"user-42\",\"aud\":\"harness-edge\"}");
    const jwt = try std.fmt.allocPrint(arena, "eyJhbGciOiJIUzI1NiJ9.{s}.sig", .{payload});
    try std.testing.expectEqualStrings("user-42", try userIdFromBearer(arena, jwt));
    try std.testing.expectEqualStrings("alice", try userIdFromBearer(arena, "alice@org1"));
    try std.testing.expectEqualStrings("bob", try userIdFromBearer(arena, "bob"));
    const pub_key: [32]u8 = @splat(1);
    const fp = fingerprint(pub_key);
    try std.testing.expectEqual(@as(usize, 24), fp.len);
    try std.testing.expectEqual(@as(u8, ' '), fp[4]);
    try std.testing.expectEqual(@as(usize, 20), std.mem.count(u8, &fp, " ") * 0 + fp.len - 4);
}