// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! A version 1 key/value secret engine, and any other engine that answers a //! plain `{"data": {...}}` envelope — `cubbyhole/`, and the read endpoints of //! the database and PKI engines among them. //! //! Unlike KV v2 there is no `data/` infix and no versioning: the API path is //! the user-facing path, a write replaces whatever was there with no history //! kept, and a delete is immediate and permanent. const std = @import("std"); const Allocator = std.mem.Allocator; const Client = @import("Client.zig"); pub const Error = Client.Error; pub const ReadError = Client.RequestError || std.json.ParseError(std.json.Scanner); pub const WriteError = Client.RequestError; pub const Options = struct { /// Mount point of the engine, without slashes. `cubbyhole` for the /// per-token cubbyhole; KV v1 mounts are conventionally `kv`. mount: []const u8 = "kv", }; /// One secret from a flat engine. Owns the parsed JSON; call `deinit`. pub const Secret = struct { parsed: std.json.Parsed(Envelope), pub const Envelope = struct { request_id: []const u8 = "", /// Seconds until the lease expires. Non-zero for dynamic engines such /// as `database/`, where the credentials must be renewed or will stop /// working. lease_duration: u64 = 0, lease_id: []const u8 = "", renewable: bool = false, data: ?std.json.Value = null, }; pub fn deinit(secret: *Secret) void { secret.parsed.deinit(); secret.* = undefined; } pub fn values(secret: Secret) ?std.json.ObjectMap { const data = secret.parsed.value.data orelse return null; return switch (data) { .object => |object| object, else => null, }; } pub fn get(secret: Secret, key: []const u8) ?std.json.Value { const object = secret.values() orelse return null; return object.get(key); } /// Value for `key` when it is a JSON string; null for a missing key or a /// value of another type. The slice is owned by the `Secret`. pub fn getString(secret: Secret, key: []const u8) ?[]const u8 { return switch (secret.get(key) orelse return null) { .string => |s| s, else => null, }; } /// How long the credentials remain valid, or null for a static secret. pub fn lease(secret: Secret) ?Lease { const value = secret.parsed.value; if (value.lease_id.len == 0) return null; return .{ .id = value.lease_id, .duration_s = value.lease_duration, .renewable = value.renewable, }; } pub const Lease = struct { id: []const u8, duration_s: u64, renewable: bool, }; }; /// Reads `mount/path`. pub fn read(client: *Client, path: []const u8, options: Options) ReadError!Secret { const gpa = client.gpa; const api_path = try mountPath(gpa, options.mount, path); defer gpa.free(api_path); return .{ .parsed = try client.readAs(Secret.Envelope, api_path, null) }; } pub const Listing = @import("kv2.zig").Listing; /// Lists the keys directly under `mount/path`. pub fn list(client: *Client, path: []const u8, options: Options) ReadError!Listing { const gpa = client.gpa; const api_path = try mountPath(gpa, options.mount, path); defer gpa.free(api_path); return .{ .parsed = try client.listAs(Listing.Envelope, api_path) }; } /// Writes `data` to `mount/path`, replacing whatever was stored there. /// /// KV v1 keeps no history, so the previous contents are gone. `data` is /// anything `std.json` can stringify, and unlike KV v2 it is sent as the /// request body directly rather than wrapped in an envelope. /// /// ```zig /// try kv1.write(&client, "legacy/creds", .{ .user = "admin" }, .{ .mount = "kv" }); /// ``` pub fn write( client: *Client, path: []const u8, data: anytype, options: Options, ) WriteError!void { const gpa = client.gpa; const api_path = try mountPath(gpa, options.mount, path); defer gpa.free(api_path); const body = try Client.encodeJson(gpa, data); defer gpa.free(body); return client.writeDiscard(api_path, body); } /// Removes `mount/path`. There is no undelete for KV v1. pub fn delete(client: *Client, path: []const u8, options: Options) WriteError!void { const gpa = client.gpa; const api_path = try mountPath(gpa, options.mount, path); defer gpa.free(api_path); return client.delete(api_path); } fn mountPath(gpa: Allocator, mount: []const u8, path: []const u8) Allocator.Error![]u8 { return std.fmt.allocPrint(gpa, "{s}/{s}", .{ std.mem.trim(u8, mount, "/"), std.mem.trimStart(u8, path, "/"), }); } const testing = std.testing; test "Secret reads a flat KV v1 envelope" { var secret: Secret = .{ .parsed = try std.json.parseFromSlice( Secret.Envelope, testing.allocator, \\{"request_id":"aa","lease_id":"","renewable":false,"lease_duration":2764800, \\ "data":{"username":"admin","password":"hunter2"},"warnings":null} , .{ .ignore_unknown_fields = true }, ) }; defer secret.deinit(); try testing.expectEqualStrings("admin", secret.getString("username").?); try testing.expectEqual(@as(?Secret.Lease, null), secret.lease()); } test "a dynamic engine response carries a renewable lease" { var secret: Secret = .{ .parsed = try std.json.parseFromSlice( Secret.Envelope, testing.allocator, \\{"lease_id":"database/creds/readonly/abc","renewable":true,"lease_duration":3600, \\ "data":{"username":"v-token-readonly-x","password":"A1a-generated"}} , .{ .ignore_unknown_fields = true }, ) }; defer secret.deinit(); const lease = secret.lease().?; try testing.expectEqual(@as(u64, 3600), lease.duration_s); try testing.expect(lease.renewable); try testing.expectEqualStrings("database/creds/readonly/abc", lease.id); }