lakebox: add ssh-key list/delete, default register --name, fix list null body (#5290)

Three related ssh-key UX changes plus a wire-format bug in `list`:

1. `ssh-key list` (new subcommand): GET /api/2.0/lakebox/ssh-keys.
Renders the user's registered keys with a `*` gutter marker on the key
matching this machine (using the existing keyHash helper from
bd72f85). `--json` for scripting.

2. `ssh-key delete <key-hash>` (new subcommand): DELETE
/api/2.0/lakebox/ssh-keys/{key_hash}.

3. `register --name` (new flag): defaults to this machine's hostname
when not provided so `ssh-key list` is meaningful across multiple
machines. Previously every locally-registered key landed with an empty
name and surfaced as `(unset)`.

4. Fix `lakebox list` against any workspace that actually has lakebox
deployed. Pieter's SDK ApiClient rewrite (08a56be) wrote the
pagination call as `Do(..., headers, query, nil, &resp)` — but the SDK's
makeRequestBody treats slot 6 (`request`) as the GET query string and
slot 5 (`queryParams`) as ignored on GET. Routing the query through slot
5 with a nil body in slot 6 makes the SDK serialize nil as the literal
JSON `null`, sent as the request body on a GET, which the lakebox
manager rejects with `INVALID_PARAMETER_VALUE: Request body must be a
JSON object`. Swap the args.

Co-authored-by: Isaac

## Changes
<!-- Brief summary of your changes that is easy to understand -->

## Why
<!-- Why are these changes needed? Provide the context that the reviewer
might be missing.
For example, were there any decisions behind the change that are not
reflected in the code itself? -->

## Tests
<!-- How have you tested the changes? -->

Tested against `dbsql-dev-testing-default` (workspace with lakebox
deployed but no sandboxes):

- [x] `lakebox list` returns `200 OK` with no body, prints "No lakeboxes
found." (previously 400'd)
- [x] `lakebox ssh-key list` renders both keys with correct column
alignment; `*` gutter marks the local key
  - [x] `lakebox ssh-key list --json` round-trips through `jq`
  - [x] `lakebox ssh-key delete <hash>` — not yet exercised end-to-end
- [x] `lakebox register --name laptop` against a clean workspace —
confirm name lands

<!-- If your PR needs to be included in the release notes for next
release,
add a separate entry in NEXT_CHANGELOG.md as part of your PR. -->

Author: akshaysingla-db

cmd/lakebox/api.go

@@ -46,10 +46,15 @@ type createRequest struct {
 
 // createResponse is the JSON body returned by POST /api/2.0/lakebox/sandboxes.
 // Mirrors the `Sandbox` proto message after JSON transcoding.
+//
+// `FQDN` is the manager's internal routing hostname — not user-actionable,
+// SSH always goes through the gateway. Tagged `omitempty` so the day the
+// manager stops returning it, both this struct and downstream `--json`
+// output drop the field cleanly instead of leaking a ghost empty string.
 type createResponse struct {
 	SandboxID string `json:"sandboxId"`
 	Status    string `json:"status"`
-	FQDN      string `json:"fqdn"`
+	FQDN      string `json:"fqdn,omitempty"`
 }
 
 // sandboxEntry is a single item in the list response.
@@ -65,7 +70,7 @@ type createResponse struct {
 type sandboxEntry struct {
 	SandboxID     string  `json:"sandboxId"`
 	Status        string  `json:"status"`
-	FQDN          string  `json:"fqdn"`
+	FQDN          string  `json:"fqdn,omitempty"`
 	Name          string  `json:"name,omitempty"`
 	CreateTime    string  `json:"createTime,omitempty"`
 	LastStartTime string  `json:"lastStartTime,omitempty"`
@@ -224,13 +229,20 @@ func (a *lakeboxAPI) list(ctx context.Context) ([]sandboxEntry, error) {
 
 // listPage fetches a single page of sandboxes. An empty `pageToken` requests
 // the first page; the server enforces ordering across pages.
+//
+// `query` is passed in slot 6 (`request`), not slot 5 (`queryParams`). On
+// GET, the SDK's makeRequestBody serializes `request` into the URL query
+// string and sends an empty body. Routing through `queryParams` instead
+// makes it write a literal `null` body, which the lakebox manager rejects
+// with `INVALID_PARAMETER_VALUE: Request body must be a JSON object`. See
+// databricks-sdk-go/httpclient/request.go:makeRequestBody.
 func (a *lakeboxAPI) listPage(ctx context.Context, pageToken string) (*listResponse, error) {
 	query := map[string]any{"page_size": listPageSize}
 	if pageToken != "" {
 		query["page_token"] = pageToken
 	}
 	var resp listResponse
-	err := a.c.Do(ctx, http.MethodGet, lakeboxAPIPath, a.headers(), query, nil, &resp)
+	err := a.c.Do(ctx, http.MethodGet, lakeboxAPIPath, a.headers(), nil, query, &resp)
 	if err != nil {
 		return nil, err
 	}
@@ -276,7 +288,41 @@ func (a *lakeboxAPI) delete(ctx context.Context, id string) error {
 	return a.c.Do(ctx, http.MethodDelete, lakeboxAPIPath+"/"+id, a.headers(), nil, nil, nil)
 }
 
-// registerKey calls POST /api/2.0/lakebox/ssh-keys.
-func (a *lakeboxAPI) registerKey(ctx context.Context, publicKey string) error {
-	return a.c.Do(ctx, http.MethodPost, lakeboxKeysAPIPath, a.headers(), nil, registerKeyRequest{PublicKey: publicKey}, nil)
+// registerKey calls POST /api/2.0/lakebox/ssh-keys. An empty `name` is
+// omitted from the wire payload so the server records "unset" rather than
+// an explicit empty string.
+func (a *lakeboxAPI) registerKey(ctx context.Context, publicKey, name string) error {
+	return a.c.Do(ctx, http.MethodPost, lakeboxKeysAPIPath, a.headers(), nil, registerKeyRequest{PublicKey: publicKey, Name: name}, nil)
+}
+
+// sshKeyEntry is a single item in the ssh-key list response. Mirrors the
+// `SshKey` proto message after JSON transcoding (`key_hash` → `keyHash`,
+// timestamps as RFC 3339 strings).
+type sshKeyEntry struct {
+	KeyHash     string `json:"keyHash"`
+	Name        string `json:"name,omitempty"`
+	CreateTime  string `json:"createTime,omitempty"`
+	LastUseTime string `json:"lastUseTime,omitempty"`
+}
+
+// listKeysResponse is the JSON body returned by GET /api/2.0/lakebox/ssh-keys.
+// Per-user keys are hard-capped at 100 server-side, so the full set fits in
+// one response — no pagination.
+type listKeysResponse struct {
+	SshKeys []sshKeyEntry `json:"sshKeys"`
+}
+
+// listKeys calls GET /api/2.0/lakebox/ssh-keys.
+func (a *lakeboxAPI) listKeys(ctx context.Context) ([]sshKeyEntry, error) {
+	var resp listKeysResponse
+	err := a.c.Do(ctx, http.MethodGet, lakeboxKeysAPIPath, a.headers(), nil, nil, &resp)
+	if err != nil {
+		return nil, err
+	}
+	return resp.SshKeys, nil
+}
+
+// deleteKey calls DELETE /api/2.0/lakebox/ssh-keys/{key_hash}.
+func (a *lakeboxAPI) deleteKey(ctx context.Context, keyHash string) error {
+	return a.c.Do(ctx, http.MethodDelete, lakeboxKeysAPIPath+"/"+keyHash, a.headers(), nil, nil, nil)
 }

cmd/lakebox/lakebox.go

@@ -32,6 +32,7 @@ Common workflows:
 	}
 
 	cmd.AddCommand(newRegisterCommand())
+	cmd.AddCommand(newSSHKeyCommand())
 	cmd.AddCommand(newSetDefaultCommand())
 	cmd.AddCommand(newSSHCommand())
 	cmd.AddCommand(newListCommand())

cmd/lakebox/register.go

@@ -18,20 +18,25 @@ import (
 const lakeboxKeyName = "lakebox_rsa"
 
 func newRegisterCommand() *cobra.Command {
+	var name string
+
 	cmd := &cobra.Command{
 		Use:   "register",
 		Short: "Register this machine for lakebox SSH access",
 		Long: `Generate a dedicated SSH key for lakebox and register it with the service.
 
 This command:
 1. Generates an RSA SSH key at ~/.ssh/lakebox_rsa (if it doesn't exist)
-2. Registers the public key with the lakebox service
+2. Registers the public key with the lakebox service, labeled with --name
+   (defaults to this machine's hostname so 'ssh-key list' is meaningful
+   across multiple machines)
 
 After registration, 'databricks lakebox ssh' will use this key automatically.
 Run this once per machine.
 
-Example:
-  databricks lakebox register`,
+Examples:
+  databricks lakebox register
+  databricks lakebox register --name my-laptop`,
 		PreRunE: root.MustWorkspaceClient,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
@@ -58,9 +63,19 @@ Example:
 				return fmt.Errorf("failed to read public key %s.pub: %w", keyPath, err)
 			}
 
+			// Default the registered key's label to this machine's hostname so
+			// `lakebox ssh-key list` is meaningful when the user has keys from
+			// multiple machines. Failed hostname lookups fall through to the
+			// server's "unset" default rather than blocking registration.
+			if name == "" {
+				if host, err := os.Hostname(); err == nil {
+					name = host
+				}
+			}
+
 			s := spin(ctx, "Registering key…")
 			defer s.Close()
-			if err := api.registerKey(ctx, string(pubKeyData)); err != nil {
+			if err := api.registerKey(ctx, string(pubKeyData), name); err != nil {
 				s.fail("Failed to register key")
 				return fmt.Errorf("failed to register key: %w", err)
 			}
@@ -72,6 +87,10 @@ Example:
 		},
 	}
 
+	cmd.Flags().StringVar(&name, "name", "",
+		"Label for the registered key (defaults to this machine's hostname). "+
+			"Pass --name= to register without a label.")
+
 	return cmd
 }
 

cmd/lakebox/sshkey.go

@@ -0,0 +1,176 @@
+package lakebox
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/databricks/cli/cmd/root"
+	"github.com/databricks/cli/libs/cmdctx"
+	"github.com/databricks/cli/libs/cmdio"
+	"github.com/spf13/cobra"
+)
+
+func newSSHKeyCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "ssh-key",
+		Short: "Manage SSH keys registered with the lakebox service",
+	}
+	cmd.AddCommand(newSSHKeyListCommand())
+	cmd.AddCommand(newSSHKeyDeleteCommand())
+	return cmd
+}
+
+func newSSHKeyDeleteCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "delete <key-hash>",
+		Short: "Delete an SSH key registered with the lakebox service",
+		Long: `Delete an SSH key registered with the lakebox service.
+
+The key hash is the identifier shown by 'databricks lakebox ssh-key list'.
+Once deleted, future SSH attempts authenticated by the corresponding
+private key will fail until the key is re-registered.
+
+Example:
+  databricks lakebox ssh-key delete a1b2c3d4e5f6...`,
+		Args:    cobra.ExactArgs(1),
+		PreRunE: root.MustWorkspaceClient,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			ctx := cmd.Context()
+			w := cmdctx.WorkspaceClient(ctx)
+			api, err := newLakeboxAPI(w)
+			if err != nil {
+				return err
+			}
+
+			hash := args[0]
+			s := spin(ctx, "Deleting key "+hash+"…")
+			defer s.Close()
+			if err := api.deleteKey(ctx, hash); err != nil {
+				s.fail("Failed to delete key")
+				return fmt.Errorf("failed to delete ssh key %s: %w", hash, err)
+			}
+			s.ok("SSH key " + cmdio.Bold(ctx, hash) + " deleted")
+			return nil
+		},
+	}
+	return cmd
+}
+
+func newSSHKeyListCommand() *cobra.Command {
+	var outputJSON bool
+
+	cmd := &cobra.Command{
+		Use:   "list",
+		Short: "List SSH keys registered with the lakebox service",
+		Long: `List SSH keys registered with the lakebox service.
+
+Each row shows the server-assigned key hash (the identifier used to
+delete the key), the user-supplied name, and create / last-use
+timestamps. The locally-registered key (from 'databricks lakebox
+register') is marked when its hash matches one of the listed entries.
+
+Examples:
+  databricks lakebox ssh-key list
+  databricks lakebox ssh-key list --json`,
+		PreRunE: root.MustWorkspaceClient,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			ctx := cmd.Context()
+			w := cmdctx.WorkspaceClient(ctx)
+			api, err := newLakeboxAPI(w)
+			if err != nil {
+				return err
+			}
+
+			keys, err := api.listKeys(ctx)
+			if err != nil {
+				return fmt.Errorf("failed to list ssh keys: %w", err)
+			}
+
+			if outputJSON {
+				enc := json.NewEncoder(cmd.OutOrStdout())
+				enc.SetIndent("", "  ")
+				return enc.Encode(keys)
+			}
+
+			if len(keys) == 0 {
+				fmt.Fprintf(cmd.ErrOrStderr(), "  %s\n",
+					cmdio.Dim(ctx, "No SSH keys registered. Run 'databricks lakebox register' to add one."))
+				return nil
+			}
+
+			// Best-effort: compute the hash of the locally-registered key so
+			// we can highlight which row belongs to this machine. Missing key
+			// file or read errors are non-fatal — just skip the marker.
+			localHash := ""
+			if path, err := lakeboxKeyPath(ctx); err == nil {
+				if data, err := os.ReadFile(path + ".pub"); err == nil {
+					localHash = keyHash(string(data))
+				}
+			}
+
+			out := cmd.OutOrStdout()
+			blank(out)
+
+			nameCol := 4
+			for _, k := range keys {
+				if l := len(k.Name); l > nameCol {
+					nameCol = l
+				}
+			}
+			nameCol += 2
+			const hashCol = 32
+			const timeCol = 20
+
+			// Leading 4-char gutter reserves space for a per-row `*` marker on
+			// the key matching this machine; header and separator leave it blank.
+			header := fmt.Sprintf("%-*s  %-*s  %-*s  %s",
+				nameCol, "NAME", hashCol, "KEY HASH", timeCol, "CREATED", "LAST USED")
+			fmt.Fprintf(out, "    %s\n", cmdio.Dim(ctx, header))
+			fmt.Fprintf(out, "    %s\n", cmdio.Dim(ctx, strings.Repeat("─", nameCol+hashCol+timeCol+timeCol+6)))
+
+			for _, k := range keys {
+				// Pad NAME manually from the raw width because cmdio.Dim
+				// wraps the cell in ANSI escapes that throw off `%-*s`.
+				displayName, visibleNameLen := k.Name, len(k.Name)
+				if displayName == "" {
+					displayName = cmdio.Dim(ctx, "(unset)")
+					visibleNameLen = len("(unset)")
+				}
+				namePad := max(nameCol-visibleNameLen, 0)
+				gutter := "    "
+				if localHash != "" && k.KeyHash == localHash {
+					gutter = "  " + cmdio.Cyan(ctx, "*") + " "
+				}
+				fmt.Fprintf(out, "%s%s%s  %-*s  %-*s  %s\n",
+					gutter,
+					displayName, strings.Repeat(" ", namePad),
+					hashCol, k.KeyHash,
+					timeCol, formatTimeShort(k.CreateTime),
+					formatTimeShort(k.LastUseTime))
+			}
+			blank(out)
+			return nil
+		},
+	}
+
+	cmd.Flags().BoolVar(&outputJSON, "json", false, "Output as JSON")
+	return cmd
+}
+
+// formatTimeShort renders an RFC 3339 timestamp as a short, compact date
+// for table display. Returns "-" for empty input; passes through the raw
+// value if it doesn't parse (so server-side schema changes don't silently
+// hide data).
+func formatTimeShort(rfc3339 string) string {
+	if rfc3339 == "" {
+		return "-"
+	}
+	t, err := time.Parse(time.RFC3339, rfc3339)
+	if err != nil {
+		return rfc3339
+	}
+	return t.Format("2006-01-02 15:04")
+}