cmd/tailscale/tslockjsonv1: export structs to unmarshal JSON for tailscale lock

This patch exports the structs used to unmarshal the JSON output of
the `tailscale lock` subcommand.

Updates #17613

Change-Id: I615723ff9dbc631e452dbf6bbdeab7b97e96dbb3
Signed-off-by: Simon Law <[email protected]>
This commit is contained in:
Simon Law authored and Simon Law committed 2026-07-30 16:23:09 -04:00
1 parent 965e2f7d0d
commit 2b879a6e95
4 files changed
+140 -109

No files matched your search

+28 -1
View File
@@ -306,7 +306,6 @@ func TestTailnetLockStatusOutput(t *testing.T) {
"NodeKey": "nodekey:0101010101010101010101010101010101010101010101010101010101010101",
"Head": "WYIVHDR7JUIXBWAJT5UPSCAILEXB7OMINDFEFEPOPNTUCNXMY2KA",
"NodeKeySigned": false,
"NodeKeySignature": null,
"TrustedKeys": [
{
"Kind": "25519",
@@ -350,6 +349,34 @@ func TestTailnetLockStatusOutput(t *testing.T) {
],
"State": 98989898
}
`,
},
{
Name: "tailnet-lock-enabled-but-empty",
Status: ipnstate.NetworkLockStatus{
Enabled: true,
Head: &head,
PublicKey: nlPub,
NodeKey: &nodeKey1,
NodeKeySigned: false,
NodeKeySignature: nil,
TrustedKeys: nil,
VisiblePeers: nil,
FilteredPeers: nil,
StateID: 98989898,
},
Want: `{
"SchemaVersion": "1",
"Enabled": true,
"PublicKey": "tlpub:0404040404040404040404040404040404040404040404040404040404040404",
"NodeKey": "nodekey:0101010101010101010101010101010101010101010101010101010101010101",
"Head": "WYIVHDR7JUIXBWAJT5UPSCAILEXB7OMINDFEFEPOPNTUCNXMY2KA",
"NodeKeySigned": false,
"TrustedKeys": [],
"VisiblePeers": [],
"FilteredPeers": [],
"State": 98989898
}
`,
},
} {
+19 -16
View File
@@ -26,7 +26,7 @@ import (
// - the raw AUM as base64-encoded bytes
// - the expanded AUM, which prints named fields for consumption by other tools
func PrintTailnetLockLogJSONV1(out io.Writer, updates []ipnstate.TailnetLockUpdate) error {
messages := make([]logMessageV1, len(updates))
messages := make([]LogMessage, len(updates))
for i, update := range updates {
var aum tka.AUM
@@ -43,10 +43,7 @@ func PrintTailnetLockLogJSONV1(out io.Writer, updates []ipnstate.TailnetLockUpda
messages[i] = toLogMessageV1(aum, update)
}
result := struct {
jsonoutput.ResponseEnvelope
Messages []logMessageV1
}{
result := LogResponse{
ResponseEnvelope: jsonoutput.ResponseEnvelope{
SchemaVersion: "1",
},
@@ -58,10 +55,16 @@ func PrintTailnetLockLogJSONV1(out io.Writer, updates []ipnstate.TailnetLockUpda
return enc.Encode(result)
}
// LogResponse is the full Tailnet Lock log output collected from the local Tailscale daemon.
type LogResponse struct {
jsonoutput.ResponseEnvelope
Messages []LogMessage
}
// toLogMessageV1 converts a [tka.AUM] and [ipnstate.TailnetLockUpdate] to the
// JSON output returned by the CLI.
func toLogMessageV1(aum tka.AUM, update ipnstate.TailnetLockUpdate) logMessageV1 {
expandedAUM := expandedAUMV1{}
func toLogMessageV1(aum tka.AUM, update ipnstate.TailnetLockUpdate) LogMessage {
expandedAUM := AUM{}
expandedAUM.MessageKind = aum.MessageKind.String()
if len(aum.PrevAUMHash) > 0 {
expandedAUM.PrevAUMHash = aum.PrevAUMHash.String()
@@ -73,7 +76,7 @@ func toLogMessageV1(aum tka.AUM, update ipnstate.TailnetLockUpdate) logMessageV1
expandedAUM.KeyID = fmt.Sprintf("tlpub:%x", keyID)
}
if state := aum.State; state != nil {
expandedState := expandedStateV1{}
expandedState := TKAState{}
if h := state.LastAUMHash; h != nil {
expandedState.LastAUMHash = h.String()
}
@@ -92,31 +95,31 @@ func toLogMessageV1(aum tka.AUM, update ipnstate.TailnetLockUpdate) logMessageV1
}
expandedAUM.Meta = aum.Meta
for _, signature := range aum.Signatures {
expandedAUM.Signatures = append(expandedAUM.Signatures, expandedSignatureV1{
expandedAUM.Signatures = append(expandedAUM.Signatures, Signature{
KeyID: fmt.Sprintf("tlpub:%x", signature.KeyID),
Signature: base64.URLEncoding.EncodeToString(signature.Signature),
})
}
return logMessageV1{
return LogMessage{
Hash: aum.Hash().String(),
AUM: expandedAUM,
Raw: base64.URLEncoding.EncodeToString(update.Raw),
}
}
// logMessageV1 is the JSON representation of an AUM as both raw bytes and
// LogMessage is the JSON representation of a [tka.AUM] as both raw bytes and
// in its expanded form, and the CLI output is a list of these entries.
type logMessageV1 struct {
// The BLAKE2s digest of the CBOR-encoded AUM. This is printed as a
type LogMessage struct {
// The BLAKE2s digest of the CBOR-encoded [tka.AUM]. This is printed as a
// base32-encoded string, e.g. KCE…XZQ
Hash string
// The expanded form of the AUM, which presents the fields in a more
// The expanded form of the [tka.AUM], which presents the fields in a more
// accessible format than doing a CBOR decoding.
AUM expandedAUMV1
AUM AUM
// The raw bytes of the CBOR-encoded AUM, encoded as base64.
// The raw bytes of the CBOR-encoded [tka.AUM], encoded as base64.
// This is useful for verifying the AUM hash.
Raw string
}
@@ -21,23 +21,13 @@ func PrintTailnetLockStatusJSONV1(out io.Writer, status *ipnstate.TailnetLockSta
SchemaVersion: "1",
}
var result any
var result StatusResponse
if status.Enabled {
result = struct {
jsonoutput.ResponseEnvelope
tailnetLockEnabledStatusV1
}{
ResponseEnvelope: responseEnvelope,
tailnetLockEnabledStatusV1: toTailnetLockEnabledStatusV1(status),
}
result = toTailnetLockEnabledStatusV1(status)
result.ResponseEnvelope = responseEnvelope
} else {
result = struct {
jsonoutput.ResponseEnvelope
tailnetLockDisabledStatusV1
}{
ResponseEnvelope: responseEnvelope,
tailnetLockDisabledStatusV1: toTailnetLockDisabledStatusV1(status),
}
result = toTailnetLockDisabledStatusV1(status)
result.ResponseEnvelope = responseEnvelope
}
enc := jsonv1.NewEncoder(out)
@@ -45,11 +35,9 @@ func PrintTailnetLockStatusJSONV1(out io.Writer, status *ipnstate.TailnetLockSta
return enc.Encode(result)
}
func toTailnetLockDisabledStatusV1(status *ipnstate.TailnetLockStatus) tailnetLockDisabledStatusV1 {
out := tailnetLockDisabledStatusV1{
tailnetLockStatusV1Base: tailnetLockStatusV1Base{
Enabled: status.Enabled,
},
func toTailnetLockDisabledStatusV1(status *ipnstate.TailnetLockStatus) StatusResponse {
out := StatusResponse{
Enabled: status.Enabled,
}
if !status.PublicKey.IsZero() {
out.PublicKey = status.PublicKey.CLIString()
@@ -60,11 +48,9 @@ func toTailnetLockDisabledStatusV1(status *ipnstate.TailnetLockStatus) tailnetLo
return out
}
func toTailnetLockEnabledStatusV1(status *ipnstate.TailnetLockStatus) tailnetLockEnabledStatusV1 {
out := tailnetLockEnabledStatusV1{
tailnetLockStatusV1Base: tailnetLockStatusV1Base{
Enabled: status.Enabled,
},
func toTailnetLockEnabledStatusV1(status *ipnstate.TailnetLockStatus) StatusResponse {
out := StatusResponse{
Enabled: status.Enabled,
}
if status.Head != nil {
@@ -79,19 +65,19 @@ func toTailnetLockEnabledStatusV1(status *ipnstate.TailnetLockStatus) tailnetLoc
if nk := status.NodeKey; nk != nil {
out.NodeKey = nk.String()
}
out.NodeKeySigned = status.NodeKeySigned
out.NodeKeySigned = &status.NodeKeySigned
if sig := status.NodeKeySignature; sig != nil {
out.NodeKeySignature = toTKANodeKeySignatureV1(sig)
}
out.TrustedKeys = []Key{} // never omit this field when enabled
for _, key := range status.TrustedKeys {
out.TrustedKeys = append(out.TrustedKeys, ipnTKAKeytoTKAKeyV1(&key))
}
out.VisiblePeers = []TrustedPeer{} // never omit this field when enabled
for _, vp := range status.VisiblePeers {
out.VisiblePeers = append(out.VisiblePeers, tkaTrustedPeerV1{
tkaPeerV1: toTKAPeerV1(vp),
NodeKeySignature: toTKANodeKeySignatureV1(&vp.NodeKeySignature),
})
out.VisiblePeers = append(out.VisiblePeers, toTrustedTKAPeerV1(vp))
}
out.FilteredPeers = []Peer{} // never omit this field when enabled
for _, fp := range status.FilteredPeers {
out.FilteredPeers = append(out.FilteredPeers, toTKAPeerV1(fp))
}
@@ -100,52 +86,46 @@ func toTailnetLockEnabledStatusV1(status *ipnstate.TailnetLockStatus) tailnetLoc
return out
}
type tailnetLockStatusV1Base struct {
// StatusResponse is the full Tailnet Lock Status output collected from the local Tailscale daemon.
type StatusResponse struct {
jsonoutput.ResponseEnvelope
// Enabled is true if Tailnet Lock is enabled.
Enabled bool
// PublicKey describes the node's tailnet-lock public key.
PublicKey string `json:"PublicKey,omitzero"`
PublicKey string `json:",omitzero"`
// NodeKey describes the node's current node-key. This field is not
// populated if the node is not operating (i.e. waiting for a login).
NodeKey string `json:"NodeKey,omitzero"`
}
NodeKey string `json:",omitzero"`
// tailnetLockDisabledStatusV1 is the JSON representation of the Tailnet Lock status
// when Tailnet Lock is disabled.
type tailnetLockDisabledStatusV1 struct {
tailnetLockStatusV1Base
}
// tailnetLockEnabledStatusV1 is the JSON representation of the Tailnet Lock status.
type tailnetLockEnabledStatusV1 struct {
tailnetLockStatusV1Base
//////////////////////////////////////////////////////////////////
// The following fields are only present when Tailnet Lock is enabled.
// Head describes the AUM hash of the leaf AUM.
Head string `json:"Head,omitzero"`
Head string `json:",omitzero"`
// NodeKeySigned is true if our node is authorized by Tailnet Lock.
NodeKeySigned bool
NodeKeySigned *bool `json:",omitzero"`
// NodeKeySignature is the current signature of this node's key.
NodeKeySignature *tkaNodeKeySignatureV1
NodeKeySignature *NodeKeySignature `json:",omitzero"`
// TrustedKeys describes the keys currently trusted to make changes
// to tailnet-lock.
TrustedKeys []tkaKeyV1
TrustedKeys []Key `json:",omitzero"`
// VisiblePeers describes peers which are visible in the netmap that
// have valid Tailnet Lock signatures.
VisiblePeers []tkaTrustedPeerV1
VisiblePeers []TrustedPeer `json:",omitzero"`
// FilteredPeers describes peers which were removed from the netmap
// (i.e. no connectivity) because they failed Tailnet Lock
// checks.
FilteredPeers []tkaPeerV1
FilteredPeers []Peer `json:",omitzero"`
// StateID is a nonce associated with the Tailnet Lock authority,
// generated upon enablement. This field is empty if Tailnet Lock
// is disabled.
// generated upon enablement.
StateID uint64 `json:"State,omitzero"`
}
+62 -41
View File
@@ -13,37 +13,37 @@ import (
"tailscale.com/tka"
)
// expandedAUMV1 is the expanded version of a [tka.AUM], designed so external tools
// AUM is the expanded version of a [tka.AUM], designed so external tools
// can read the AUM without knowing our CBOR definitions.
type expandedAUMV1 struct {
type AUM struct {
MessageKind string
PrevAUMHash string `json:"PrevAUMHash,omitzero"`
PrevAUMHash string `json:",omitzero"`
// Key encodes a public key to be added to the key authority.
// This field is used for AddKey AUMs.
Key tkaKeyV1 `json:"Key,omitzero"`
Key Key `json:",omitzero"`
// KeyID references a public key which is part of the key authority.
// This field is used for RemoveKey and UpdateKey AUMs.
KeyID string `json:"KeyID,omitzero"`
KeyID string `json:",omitzero"`
// State describes the full state of the key authority.
// This field is used for Checkpoint AUMs.
State expandedStateV1 `json:"State,omitzero"`
State TKAState `json:",omitzero"`
// Votes and Meta describe properties of a key in the key authority.
// These fields are used for UpdateKey AUMs.
Votes uint `json:"Votes,omitzero"`
Meta map[string]string `json:"Meta,omitzero"`
Votes uint `json:",omitzero"`
Meta map[string]string `json:",omitzero"`
// Signatures lists the signatures over this AUM.
Signatures []expandedSignatureV1 `json:"Signatures,omitzero"`
Signatures []Signature `json:",omitzero"`
}
// tkaKeyV1 is the expanded version of a [tka.Key], which describes
// Key is the expanded version of a [tka.Key], which describes
// the public components of a key known to tailnet-lock.
type tkaKeyV1 struct {
Kind string `json:"Kind,omitzero"`
type Key struct {
Kind string `json:",omitzero"`
// Votes describes the weight applied to signatures using this key.
Votes uint
@@ -53,13 +53,13 @@ type tkaKeyV1 struct {
// Meta describes arbitrary metadata about the key. This could be
// used to store the name of the key, for instance.
Meta map[string]string `json:"Meta,omitzero"`
Meta map[string]string `json:",omitzero"`
}
// ipnTKAKeytoTKAKeyV1 converts an [ipnstate.TKAKey] to the JSON output returned
// by the CLI.
func ipnTKAKeytoTKAKeyV1(key *ipnstate.TKAKey) tkaKeyV1 {
return tkaKeyV1{
func ipnTKAKeytoTKAKeyV1(key *ipnstate.TKAKey) Key {
return Key{
Kind: key.Kind,
Votes: key.Votes,
Public: key.Key.CLIString(),
@@ -69,8 +69,8 @@ func ipnTKAKeytoTKAKeyV1(key *ipnstate.TKAKey) tkaKeyV1 {
// toTKAKeyV1 converts a [tka.Key] to the JSON output returned
// by the CLI.
func toTKAKeyV1(key *tka.Key) tkaKeyV1 {
return tkaKeyV1{
func toTKAKeyV1(key *tka.Key) Key {
return Key{
Kind: key.Kind.String(),
Votes: key.Votes,
Public: fmt.Sprintf("tlpub:%x", key.Public),
@@ -78,20 +78,20 @@ func toTKAKeyV1(key *tka.Key) tkaKeyV1 {
}
}
// tkaNodeKeySignatureV1 is the JSON representation of a [tka.NodeKeySignature],
// NodeKeySignature is the JSON representation of a [tka.NodeKeySignature],
// which describes a signature that authorizes a specific node key.
type tkaNodeKeySignatureV1 struct {
type NodeKeySignature struct {
// SigKind identifies the variety of signature.
SigKind string
// PublicKey identifies the key.NodePublic which is being authorized.
// SigCredential signatures do not use this field.
PublicKey string `json:"PublicKey,omitzero"`
PublicKey string `json:",omitzero"`
// KeyID identifies which key in the tailnet key authority should
// be used to verify this signature. Only set for SigDirect and
// SigCredential signature kinds.
KeyID string `json:"KeyID,omitzero"`
KeyID string `json:",omitzero"`
// Signature is the packed (R, S) ed25519 signature over all other
// fields of the structure.
@@ -99,15 +99,15 @@ type tkaNodeKeySignatureV1 struct {
// Nested describes a NodeKeySignature which authorizes the node-key
// used as Pubkey. Only used for SigRotation signatures.
Nested *tkaNodeKeySignatureV1 `json:"Nested,omitzero"`
Nested *NodeKeySignature `json:",omitzero"`
// WrappingPubkey specifies the ed25519 public key which must be used
// to sign a Signature which embeds this one.
WrappingPublicKey string `json:"WrappingPublicKey,omitzero"`
WrappingPublicKey string `json:",omitzero"`
}
func toTKANodeKeySignatureV1(sig *tka.NodeKeySignature) *tkaNodeKeySignatureV1 {
out := tkaNodeKeySignatureV1{
func toTKANodeKeySignatureV1(sig *tka.NodeKeySignature) *NodeKeySignature {
out := NodeKeySignature{
SigKind: sig.SigKind.String(),
}
if len(sig.Pubkey) > 0 {
@@ -126,10 +126,10 @@ func toTKANodeKeySignatureV1(sig *tka.NodeKeySignature) *tkaNodeKeySignatureV1 {
return &out
}
// tkaPeerV1 is the JSON representation of an [ipnstate.TKAPeer], which describes
// Peer is the JSON representation of an [ipnstate.TKAPeer], which describes
// a peer and its Tailnet Lock details.
type tkaPeerV1 struct {
// Stable ID, i.e. [tailcfg.StableNodeID]
type Peer struct {
// Stable ID, i.e. [tailscale.com/tailcfg.StableNodeID]
ID string
// DNS name
@@ -142,17 +142,27 @@ type tkaPeerV1 struct {
NodeKey string
}
// tkaPeerV1 is the JSON representation of a trusted [ipnstate.TKAPeer], which
// has a node key signature.
type tkaTrustedPeerV1 struct {
tkaPeerV1
// TrustedPeer is the JSON representation of a trusted [ipnstate.TKAPeer], which
// has a node key signature in addition to [Peer].
type TrustedPeer struct {
// Stable ID, i.e. [tailscale.com/tailcfg.StableNodeID]
ID string
// DNS name
DNSName string
// Tailscale IP(s) assigned to this node
TailscaleIPs []string
// The node's public key
NodeKey string
// The node's key signature
NodeKeySignature *tkaNodeKeySignatureV1 `json:"NodeKeySignature,omitzero"`
NodeKeySignature *NodeKeySignature `json:",omitzero"`
}
func toTKAPeerV1(peer *ipnstate.TKAPeer) tkaPeerV1 {
out := tkaPeerV1{
func toTKAPeerV1(peer *ipnstate.TKAPeer) Peer {
out := Peer{
DNSName: peer.Name,
ID: string(peer.StableID),
}
@@ -164,19 +174,30 @@ func toTKAPeerV1(peer *ipnstate.TKAPeer) tkaPeerV1 {
return out
}
// expandedSignatureV1 is the expanded form of a [tka.Signature], which
func toTrustedTKAPeerV1(peer *ipnstate.TKAPeer) TrustedPeer {
out := toTKAPeerV1(peer)
return TrustedPeer{
DNSName: out.DNSName,
ID: out.ID,
TailscaleIPs: out.TailscaleIPs,
NodeKey: out.NodeKey,
NodeKeySignature: toTKANodeKeySignatureV1(&peer.NodeKeySignature),
}
}
// Signature is the expanded form of a [tka.Signature], which
// describes a signature over an AUM. This signature can be verified
// using the key referenced by KeyID.
type expandedSignatureV1 struct {
type Signature struct {
KeyID string
Signature string
}
// expandedStateV1 is the expanded version of a [tka.State], which describes
// TKAState is the expanded version of a [tka.TKAState], which describes
// Tailnet Key Authority state at an instant in time.
type expandedStateV1 struct {
type TKAState struct {
// LastAUMHash is the blake2s digest of the last-applied AUM.
LastAUMHash string `json:"LastAUMHash,omitzero"`
LastAUMHash string `json:",omitzero"`
// DisablementValues are KDF-derived values used to verify that a caller
// possesses a valid DisablementSecret. These values are used during the
@@ -190,7 +211,7 @@ type expandedStateV1 struct {
//
// 1. The signing nodes currently trusted by the TKA.
// 2. Ephemeral keys that were used to generate pre-signed auth keys.
Keys []tkaKeyV1
Keys []Key
// StateID's are nonces, generated on enablement and fixed for
// the lifetime of the Tailnet Key Authority.