Documentation
¶
Overview ¶
Package sidecar defines the wire protocol shared between the CLI client (running inside a sandbox) and the auth sidecar proxy (running in a trusted environment). Communication uses plain HTTP.
Index ¶
Constants ¶
const ( // HeaderProxyVersion carries the wire-protocol version (e.g. ProtocolV1). // Servers must reject requests whose version they do not understand. The // value is also included in the canonical signing string so that a request // signed for one version cannot be replayed as another. HeaderProxyVersion = "X-Lark-Proxy-Version" // HeaderProxyTarget carries the original request host (e.g. "open.feishu.cn"). HeaderProxyTarget = "X-Lark-Proxy-Target" // HeaderProxyIdentity carries the resolved identity type ("user" or "bot"). HeaderProxyIdentity = "X-Lark-Proxy-Identity" // HeaderProxySignature carries the HMAC-SHA256 hex signature. HeaderProxySignature = "X-Lark-Proxy-Signature" // HeaderProxyTimestamp carries the Unix epoch seconds string used in signing. HeaderProxyTimestamp = "X-Lark-Proxy-Timestamp" // HeaderBodySHA256 carries the hex-encoded SHA-256 digest of the request body. HeaderBodySHA256 = "X-Lark-Body-SHA256" // HeaderProxyAuthHeader tells the sidecar which header to inject the real // token into. Defaults to "Authorization" for standard OpenAPI requests. // MCP requests use "X-Lark-MCP-UAT" or "X-Lark-MCP-TAT". HeaderProxyAuthHeader = "X-Lark-Proxy-Auth-Header" )
Proxy request headers set by the CLI transport interceptor.
const ( HeaderMCPUAT = "X-Lark-MCP-UAT" HeaderMCPTAT = "X-Lark-MCP-TAT" )
MCP auth headers used by the Lark MCP protocol.
const ( SentinelUAT = "sidecar-managed-uat" // User Access Token placeholder SentinelTAT = "sidecar-managed-tat" // Tenant Access Token placeholder )
Sentinel token values returned by the noop credential provider. These are placeholder strings that flow through the SDK auth pipeline but are stripped by the transport interceptor before reaching the sidecar.
const ( IdentityUser = "user" IdentityBot = "bot" )
IdentityUser and IdentityBot are the wire values for HeaderProxyIdentity.
const DefaultListenAddr = "127.0.0.1:16384"
DefaultListenAddr is the default sidecar listen address (localhost only).
const MaxTimestampDrift = 60
MaxTimestampDrift is the maximum allowed difference (in seconds) between the request timestamp and the server's current time.
const ProtocolV1 = "v1"
ProtocolV1 is the wire-protocol version string embedded in every signed request. Servers must reject requests whose HeaderProxyVersion is not a version they understand. Bump this constant (and update the canonical string) for any breaking change to signing inputs.
Variables ¶
This section is empty.
Functions ¶
func BodySHA256 ¶
BodySHA256 returns the hex-encoded SHA-256 digest of body. An empty or nil body produces the SHA-256 of the empty string.
func ProxyHost ¶
ProxyHost extracts the host:port from an AUTH_PROXY URL. Input is expected to be an HTTP URL like "http://127.0.0.1:16384". Returns the host:port portion for URL rewriting.
func Sign ¶
func Sign(key []byte, req CanonicalRequest) string
Sign computes the HMAC-SHA256 signature over the canonical request string.
func Timestamp ¶
func Timestamp() string
Timestamp returns the current Unix epoch seconds as a string.
func ValidateProxyAddr ¶
ValidateProxyAddr validates the LARKSUITE_CLI_AUTH_PROXY value. Accepted formats:
- http://host:port
- host:port (bare address, treated as http)
Host must be loopback or in sameHostAliases. The sidecar pattern is inherently same-machine; cross-machine deployment is a different product and is not supported by this feature.
https:// is rejected because sidecar is a same-host pattern: loopback and virtual same-host bridges don't traverse any untrusted medium, so TLS adds no security. Cross-machine deployment is out of scope (see the host constraint above), so there is no scenario today where https provides a real benefit over http on loopback.
userinfo (user:pass@) is rejected unconditionally — the sidecar protocol does not use basic auth, and the syntactic slot exists only as a phishing vector (e.g. http://127.0.0.1@attacker.com).
Returns an error if the value is not a valid proxy address.
Types ¶
type CanonicalRequest ¶
type CanonicalRequest struct {
Version string // e.g. ProtocolV1
Method string // e.g. "GET", "POST"
Host string // e.g. "open.feishu.cn"
PathAndQuery string // e.g. "/open-apis/calendar/v4/events?page_size=50"
BodySHA256 string // hex-encoded SHA-256 of the request body
Timestamp string // Unix epoch seconds string
Identity string // IdentityUser or IdentityBot
AuthHeader string // header the server should inject the real token into
}
CanonicalRequest is the set of fields covered by the HMAC signature. Clients and servers must populate every field identically for verification to succeed; any field that is forwarded but *not* covered by this struct can be tampered with inside the MaxTimestampDrift replay window without invalidating the signature.
Version must be set to a known protocol constant (ProtocolV1). It is the first field in the canonical string so that a future v2 with different structure cannot be confused for v1 output under the same key.
Source Files