Might be good to say what the semantics are for how it gets used / how authentication works?

It's identical to how all the machine requests work (with a Version and then a NodeKey that must match the machine key used for the ts2021 transport) but I can say a bit more.

done

I'd suggest s/node's attributes/device posture attributes/g to align with how we're calling these in the docs and minimize potential confusion with nodeAttrs.

done

I am curious why we don't call DoNoiseRequest here, which already checks for panicOnUse, and seems to use the same transport.

This comment implies that using getConn directly (like doWithBody does) would attach node key proofs, but I don't think that's actually true? I only see KeyProvingNoiseRoundTripper used in tsnet.

I am likely missing something, since it's my first time taking a closer look at noise client, but I would like to understand it better.

Oh, right. That was added for one caller ages ago that needed to do it from afar, but all the existing callers (who used the helpers that automatically JSON-encode the request body) were never updated to use it, because the exported one isn't as helpful.

But then apparently a handful of people have since moved on to using DoNoiseRequest directly, and doing the JSON encoding themselves. But those callers aren't setting the load balancer hint header:

func addLBHeader(req *http.Request, nodeKey key.NodePublic) {
	if !nodeKey.IsZero() {
		req.Header.Add(tailcfg.LBHeader, nodeKey.String())
	}
}

Which makes the load balancer work a bit harder when it's absent.

There's about a 50/50 split between the two styles right now and I don't want to clean them up one way or another in this PR, but I do want to clean it up in its own change later.

I'll keep this as is for now (as it calls addLBHeader) but yeah, I don't like the split.

I'd suggest linking to https://tailscale.com/s/api-device-posture-attrs (which I am adding in https://github.com/tailscale/tailscale-www/pull/7256) to provide more context on supported keys and values.

done

I suspect at some point we might want clients to be able to set an expiry time, like our HTTP API supports: https://tailscale.com/api#tag/devices/POST/device/{deviceId}/attributes/{attributeKey}

Would that be another map of key->time.Time? (similar to the expiries field returned by our get api)

Or should the API be mapping keys to another struct, which would contain value alongside an optional expiry time?

How about we keep it any-to-any now (where the value any can be float64/bool/string/nil) and in the future we could add a struct (JSON object) type for other metadata like expiries?