vaultkit 1.2.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 992511b9fff48dc39ffa343776721e9c24077c00cfdbe97b9f98e0f1454f4093
-  data.tar.gz: bcc02c8d21f7d0e66d1b30fd16ef2080aedf8271ac7159d775f05bf1e6db15d1
+  metadata.gz: 17014258d6102f66c5d3479d541fbc2540f5f4b988c87c46c0bf8a7d17340043
+  data.tar.gz: 83c4694cc2efd7bc579c2fbc29bf2f556fd22539ffae1a23f52ce741b55f126e
 SHA512:
-  metadata.gz: dd8c2496c757661ade482f3ac01bf68ab1d073903db14dec88d9a4d4d40721beb9ea36e8942deb4f9296b3f6e6f49014d1724b8bbfb3d67d351ed886024629bf
-  data.tar.gz: 2881996c7f00bb58a92a62d00dea1408ab2ea42c0e0d3acc2fb0f6fc782ac27aa6eac943b458ddcd5dee416debb8714b0f285a7f6954db9d2c9e00290f2206a7
+  metadata.gz: 452fad9cc3ed91570302342f4e319c26cf62c3446bb008f225719f01487731de5f953046ce67b8dbe0b33e6cad6406fa36d1b6e35cb1092a12bb7826e8999fa0
+  data.tar.gz: c6ec74cacd3cc839ff3160413c86513f5f3a0d8a036f6a6bb938bfc56bc473215583dd9e63414c05c83710ba1c2d6d9a8c70dccd57fde6760e9f125058f6d34e

data/README.md

@@ -43,7 +43,6 @@ The VaultKit CLI provides command-line access to VaultKit for:
 | **Datasource Admin** | Register and manage database connections (admin only) |
 | **Schema Discovery** | Scan datasources and detect schema drift |
 | **Policy Deployment** | Build, validate, and deploy policy bundles |
-| **Audit Queries** | Search and export audit logs |
 
 ### Mental Model
 
@@ -266,13 +265,17 @@ vkit request --aql '{
 }'
 
 # Output:
-# ✓ Request granted immediately
-# Grant ID: gr_abc123xyz
-# TTL: 4 hours
-# Use: vkit fetch --grant gr_abc123xyz
+# ✅ ACCESS GRANTED
+# Grant Ref: g_public_reports_3f9a
+# Request ID: 8d1c0a2e-… (look it up under Activity in the console)
+# Expires: 2024-01-15 18:00:00 UTC
+# Masked Fields: none
+#
+# To execute and retrieve the data, run:
+#    vkit fetch --grant g_public_reports_3f9a
 
 # 2. Fetch data
-vkit fetch --grant gr_abc123xyz --format table
+vkit fetch --grant g_public_reports_3f9a --format table
 ```
 
 ### Workflow 2: Approval Required
@@ -286,17 +289,17 @@ vkit request --aql '{
 }'
 
 # Output:
-# ⏳ Approval required
-# Request ID: req_20240115_xyz789
-# Approver: finance_manager
+# ⏳ QUEUED for approval
+# Request ID: 3b7e19c4-… (look it up under Activity in the console)
+# Approver roles: finance_manager
 # Reason: Financial data requires manager approval
-# Status: PENDING
+#
+# Once it's approved, run the same request again to get the data.
 
 # 2. Check status
 vkit requests list --state pending
 
-# 3. After approval, fetch data
-vkit fetch --grant gr_approved_abc123
+# 3. After approval, run the same request again; it returns the rows
 ```
 
 ### Workflow 3: Denied Access
@@ -309,11 +312,9 @@ vkit request --aql '{
 }'
 
 # Output:
-# ❌ Request denied
+# ❌ DENIED
 # Reason: Direct payment card data access forbidden
-# Policy: pci_dss_restrictions
-# Alternative: Use tokenized_card_id field instead
-# Audit ID: audit_20240115_denied_123
+# Request ID: 7f29e0aa-… (look it up under Activity in the console)
 ```
 
 ---
@@ -869,60 +870,71 @@ vkit policy show <POLICY_ID>
 
 ---
 
-### Audit Commands
+### Agent Token Commands (Admin Only)
 
-#### `vkit audit query`
+Agents (an MCP server, a scheduled job, a coding assistant) authenticate with
+an agent token instead of a login. An agent is every token with the same
+`--name`; the console's Agents page groups them that way.
 
-Search audit logs.
+#### `vkit agents tokens create`
 
 ```bash
-vkit audit query [OPTIONS]
+vkit agents tokens create --name NAME [OPTIONS]
 ```
 
 **Options:**
-- `--user` — Filter by user email
-- `--action` — Filter by action: `granted`, `denied`, `pending`
-- `--dataset` — Filter by dataset name
-- `--days` — Look back N days (default: 7)
-- `--limit` — Number of results (default: 100)
-- `--format` — Output format: `json`, `table`, `csv`
+- `--name` — The agent's name (e.g. `incident-bot`); tokens with the same name are one agent
+- `--label` — What this token is for, shown next to it in the console (e.g. `"PagerDuty runner"`)
+- `--for` — Email of the person the agent acts for. Their Activity shows the agent's requests, so a member can follow what an agent does on their behalf. Must be an active member of your organization. Without it the agent acts for no one, and only admins see its requests.
+- `--expires-in` — Lifetime: `1h`, `24h`, `30d` (default: no expiry)
+- `--role`, `--clearance`, `--region`, `--tenant` — What policies see for this token
+
+The token is printed once; store it straight away. The console never shows it.
 
-**Examples:**
 ```bash
-# All queries by a user
-vkit audit query --user analyst@company.com --days 30
+vkit agents tokens create --name incident-bot --label "PagerDuty runner" \
+  --for sam@acme.test --expires-in 30d
+```
 
-# Denied access attempts
-vkit audit query --action denied --days 7
+`--for` names who the agent acts for. It's separate from who created the
+token (you), which the console shows as "Created by".
 
-# Access to specific dataset
-vkit audit query --dataset customers --action granted
+#### `vkit agents tokens list`
 
-# Export to CSV
-vkit audit query --user analyst@company.com --format csv --output audit_report.csv
+```bash
+vkit agents tokens list [--agent NAME] [--format table|json]
 ```
 
-#### `vkit audit export`
-
-Export audit logs for compliance reporting.
+#### `vkit agents tokens revoke`
 
 ```bash
-vkit audit export --start-date <DATE> --end-date <DATE> [OPTIONS]
+vkit agents tokens revoke --token PREFIX_OR_ID --reason "Leaked in CI logs"
 ```
 
-**Options:**
-- `--start-date` — Start date (YYYY-MM-DD)
-- `--end-date` — End date (YYYY-MM-DD)
-- `--format` — Output format: `json`, `csv` (default: `csv`)
-- `--output` — Output file path
+`--reason` is required and recorded in the audit log. The token stops working
+at once: its live grants are revoked, and a request already in flight with it
+gets no rows.
+
+`--for` needs a control plane with the console's Agents page; an older one
+ignores it, and the token acts for no one. That control plane also refuses a
+revoke without a reason, so older CLI versions can't revoke against it.
+
+### Audit Log
+
+There's no `vkit audit` command. Every request, decision and revoke is in the
+audit log; read it in the console:
+
+- **Activity** lists every request: who asked, what was decided and why, and
+  what ran. Filter by decision, agent, person, dataset or time, and open one
+  by the request ID that `vkit request` prints.
+- **Export CSV** on the Activity page downloads the filtered view.
+- A refused request, for example one made with a revoked agent token, prints
+  its code and request ID too:
 
-**Example:**
 ```bash
-vkit audit export \
-  --start-date 2024-01-01 \
-  --end-date 2024-01-31 \
-  --format csv \
-  --output compliance_reports/january_2024.csv
+# API 401: Agent token vkit_agent_f5f5d9 was revoked at 2026-11-04T19:55:11Z: Leaked in CI logs
+# Code: token_revoked
+# Request ID: 7973fcba-… (look it up under Activity in the console)
 ```
 
 ---
@@ -1082,9 +1094,7 @@ docker compose up
 
 **Problem:**
 ```
-Error: Grant has expired
-Grant ID: gr_abc123xyz
-Expired at: 2024-01-15 12:00:00 UTC
+API 403: Grant expired
 ```
 
 **Solutions:**

data/lib/vkit/cli/api/client.rb

@@ -83,7 +83,7 @@ module Vkit
         
           when 403
             if body.is_a?(Hash) && body.key?("error")
-              raise APIError.new(code, body["error"])
+              raise APIError.from_body(code, body)
             else
               # Valid domain response (e.g. policy denied)
               body
@@ -93,21 +93,39 @@ module Vkit
             # Queued for approval
             body
         
-          when 422
-            raise APIError.new(code, body["error"] || body)
-        
           else
-            raise APIError.new(code, body["error"] || body)
+            raise APIError.from_body(code, body)
           end
         end        
       end
 
+      # The control plane's { error, code, request_id }. code says why in a
+      # word (token_revoked, token_expired), and request_id finds the request
+      # on the console's Activity page.
       class APIError < StandardError
-        attr_reader :status
+        attr_reader :status, :error, :code, :request_id
+
+        def self.from_body(status, body)
+          return new(status, body) unless body.is_a?(Hash)
+
+          new(status, body["error"] || body, code: body["code"], request_id: body["request_id"])
+        end
 
-        def initialize(status, message)
+        def initialize(status, error, code: nil, request_id: nil)
           @status = status
-          super("API #{status}: #{message}")
+          @error = error
+          @code = code
+          @request_id = request_id
+          super(describe)
+        end
+
+        private
+
+        def describe
+          lines = ["API #{status}: #{error}"]
+          lines << "Code: #{code}" if code
+          lines << "Request ID: #{request_id} (look it up under Activity in the console)" if request_id
+          lines.join("\n")
         end
       end
     end

data/lib/vkit/cli/base_cli.rb

@@ -115,7 +115,7 @@ module Vkit
 
       desc "grant:revoke", "Revoke a grant"
       option :grant, type: :string, required: true
-      option :reason, type: :string
+      option :reason, type: :string, required: true, desc: "Why it's revoked; recorded in the audit log"
       option :force, type: :boolean, default: false
       define_method("grant:revoke") do
         Commands::GrantRevokeCommand.new.call(
@@ -335,9 +335,14 @@ module Vkit
           option :tenant, type: :string, desc: "Tenant this token acts for on tenant-scoped datasets"
           option :clearance, type: :string, desc: "Clearance policies see: low, medium or high"
           option :region, type: :string, desc: "Region policies see: EU, US, CA or APAC"
+          option :label, type: :string, desc: "What this token is for, shown in the console (e.g. \"PagerDuty runner\")"
+          option :for, type: :string, banner: "EMAIL",
+                       desc: "Email of the person the agent acts for; they see its requests in Activity"
           def create
             Commands::AgentTokensCreateCommand.new.call(
               name: options[:name],
+              label: options[:label],
+              for: options[:for],
               expires_in: options[:expires_in],
               role: options[:role],
               tenant: options[:tenant],
@@ -349,10 +354,12 @@ module Vkit
           # agents tokens revoke
           desc "revoke", "Revoke an agent token"
           option :token, required: true, desc: "Token ID or prefix"
+          option :reason, type: :string, required: true, desc: "Why it's revoked; recorded in the audit log"
           option :force, type: :boolean, default: false, desc: "Skip confirmation"
           def revoke
             Commands::AgentTokensRevokeCommand.new.call(
               token: options[:token],
+              reason: options[:reason],
               force: options[:force]
             )
           end

data/lib/vkit/cli/commands/agent_tokens_create_command.rb

@@ -25,6 +25,8 @@ module Vkit
             puts
 
             puts "🧠 Name:       #{token["name"]}"
+            puts "📝 Label:      #{token["label"]}" if token["label"]
+            puts "👤 Acts for:   #{acts_for(token)}"
             puts "🎭 Role:       #{token["role"]}"
             puts "🏢 Tenant:     #{token["tenant"]}" if token["tenant"]
             puts "🛡  Clearance:  #{token["clearance"]}" if token["clearance"]
@@ -49,6 +51,9 @@ module Vkit
         def build_body(options)
           body = {
             name: options.fetch(:name),
+            label: options[:label],
+            # Resolved to a member of your organization by the control plane.
+            user_email: options[:for],
             role: options[:role],
             tenant: options[:tenant],
             clearance: options[:clearance],
@@ -62,6 +67,13 @@ module Vkit
           body
         end
 
+        def acts_for(token)
+          person = token["acts_for"]
+          return "no one (its requests show only to admins)" unless person
+
+          person["name"] == person["email"] ? person["email"] : "#{person["name"]} <#{person["email"]}>"
+        end
+
         def parse_expires_in(value)
           number = value.to_i
         

data/lib/vkit/cli/commands/agent_tokens_list_command.rb

@@ -42,6 +42,8 @@ module Vkit
                   "ID"         => t["id"],
                   "Agent"      => t["name"],
                   "Prefix"     => t["prefix"],
+                  "Label"      => t["label"] || "-",
+                  "Acts For"   => t.dig("acts_for", "email") || "-",
                   "Expires At" => t["expires_at"] || "never",
                   "Revoked At" => t["revoked_at"] || "-",
                   "Created At" => t["created_at"]

data/lib/vkit/cli/commands/agent_tokens_revoke_command.rb

@@ -8,6 +8,9 @@ module Vkit
       class AgentTokensRevokeCommand < BaseCommand
         def call(options)
           token_ref = options.fetch(:token)
+          reason = options[:reason].to_s.strip
+          # The control plane refuses a revoke without one.
+          raise "A reason is required (--reason)" if reason.empty?
 
           with_auth do
             user = credential_store.user
@@ -21,7 +24,7 @@ module Vkit
 
             authenticated_client.post(
               "/api/v1/orgs/#{org}/agent_tokens/#{token["id"]}/revoke",
-              body: {}
+              body: { reason: reason }
             )
 
             puts "🛑 AGENT TOKEN REVOKED"
@@ -29,8 +32,9 @@ module Vkit
             puts "🧠 Name:   #{token["name"]}"
             puts "🏷  Prefix: #{token["prefix"]}"
             puts "🆔 ID:     #{token["id"]}"
+            puts "📝 Reason: #{reason}"
             puts
-            puts "✅ The token is no longer valid."
+            puts "✅ The token is no longer valid, and its grants are revoked."
           end
         end
 

data/lib/vkit/cli/commands/approval_command.rb

@@ -61,7 +61,7 @@ module Vkit
               puts "   The grant is issued once every role has approved."
             else
               puts "✅ Approved request #{id}"
-              puts "   → Grant Ref: #{res["grant_ref"] || res["grant_id"]}"
+              puts "   → Grant Ref: #{res["grant_ref"]}"
               puts "   → Expires:   #{res["expires_at"]}"
             end
           end

data/lib/vkit/cli/commands/grant_revoke_command.rb

@@ -5,6 +5,10 @@ module Vkit
     module Commands
       class GrantRevokeCommand < BaseCommand
         def call(grant_ref:, reason:, force:)
+          reason = reason.to_s.strip
+          # The control plane refuses a revoke without one.
+          raise "A reason is required (--reason)" if reason.empty?
+
           with_auth do
             user = credential_store.user
             org  = user["organization_slug"]
@@ -14,7 +18,7 @@ module Vkit
             unless force
               puts "⚠️  You are about to revoke grant: #{grant_ref}"
               puts "   Organization: #{org}"
-              puts "   Reason: #{reason || 'Grant revoked via CLI'}"
+              puts "   Reason: #{reason}"
               print "Continue? (y/N): "
               answer = STDIN.gets.strip
               return puts("Aborted.") unless answer.downcase == "y"

data/lib/vkit/cli/commands/request_command.rb

@@ -43,9 +43,17 @@ module Vkit
 
         private
 
+        # Every response names its request; the console's Activity page
+        # finds it by this id.
+        def print_request_id(result)
+          return if result["request_id"].to_s.empty?
+
+          puts "Request ID: #{result["request_id"]} (look it up under Activity in the console)"
+        end
+
         def print_queued(result)
           puts "⏳ QUEUED for approval"
-          puts "Request ID: #{result["request_id"]}"
+          print_request_id(result)
 
           roles = ApprovalRoles.required_roles(result)
           puts "Approver roles: #{roles.join(', ')}" if roles.any?
@@ -67,6 +75,7 @@ module Vkit
           when "denied"
             puts "❌ DENIED"
             puts "Reason: #{result["reason"]}"
+            print_request_id(result)
             exit 2
 
           # The control plane answers "pending_approval"; "queued" is what
@@ -79,7 +88,8 @@ module Vkit
             expires_at = Time.parse(result["expires_at"]).getlocal
 
             puts "✅ ACCESS GRANTED"
-            puts "Grant ID: #{result["grant_id"]}"
+            puts "Grant Ref: #{result["grant_ref"]}"
+            print_request_id(result)
             puts "Expires: #{expires_at.strftime("%Y-%m-%d %H:%M:%S %Z")}"
 
             if (mask = result["masked_fields"]) && mask.any?
@@ -90,7 +100,7 @@ module Vkit
 
             puts
             puts "To execute and retrieve the data, run:"
-            puts "   vkit fetch --grant #{result["grant_ref"] || result["grant_id"]}"
+            puts "   vkit fetch --grant #{result["grant_ref"]}"
             exit 0
 
           when "ok"
@@ -102,6 +112,8 @@ module Vkit
             end
 
             puts "✅ OK — #{rows.size} rows"
+            puts "Grant Ref: #{result["grant_ref"]} (reused)" if result["grant_ref"]
+            print_request_id(result)
 
             if meta.any?
               puts "ℹ️  Query Metadata:"
@@ -116,6 +128,7 @@ module Vkit
           else
             puts "❓ Unexpected response:"
             puts result.inspect
+            print_request_id(result) if result.is_a?(Hash)
             exit 1
           end
         end

data/lib/vkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vkit
-  VERSION = "1.2.2"
+  VERSION = "1.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vaultkit
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.3.0
 platform: ruby
 authors:
 - Nnamdi Ogundu
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-30 00:00:00.000000000 Z
+date: 2026-11-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor