config

Documentation

Overview

Package config loads Skybridge configuration from the environment. All keys are prefixed SKYBRIDGE_. The same binary runs as either an egress agent or a relay gateway depending on mode.

Index

• Constants
• type Agent
  • func LoadAgent() Agent
  • func (a Agent) ClientTLSConfigured() bool
  • func (a Agent) TargetByName(name string) (tunnel.Target, bool)
  • func (a Agent) UpstreamTLSEnabled() bool
• type ClientListener
• type Edge
  • func LoadEdge() Edge
  • func (e Edge) StudioEnabled() bool
  • func (e Edge) WireProxyEnabled() bool
• type Gateway
  • func LoadGateway() Gateway

Constants

const (
	ModeListener = "listener" // agent itself listens for native clients (clients reach the agent)
	ModeTunnel   = "tunnel"   // agent dials the relay gateway and serves streams over an egress tunnel
)

Mode selects how the agent exposes databases.

Types

type Agent

type Agent struct {
	Mode string // listener | tunnel

	// Listener-mode (single target).
	DBType       string // postgres | mysql | mongodb
	ListenAddr   string // local listen address for native clients, e.g. ":15432"
	UpstreamAddr string // upstream database address host:port (dialed by the agent)

	// Tunnel-mode (egress to the gateway, many targets).
	GatewayAddr string          // gateway agent endpoint host:port (the agent dials OUT to this)
	AgentID     string          // stable agent identity (an org key may be shared by many agents)
	OrgID       string          // tenant this agent belongs to (for session attribution)
	Token       string          // shared registration token
	Targets     []tunnel.Target // databases this agent can reach

	// Masking (shared by both modes).
	MaskAnalyzeURL   string // empty disables the default remote masker
	MaskAnonymizeURL string
	MaskLanguage     string
	PIIOverlay       map[string]string // column->token overlay you define (off by default)

	// Dynamic overlay source (optional). When PIIOverlayURL is set the agent fetches the org's
	// projected column->token overlay from the control plane at startup and re-fetches on an
	// interval, hot-swapping the overlay rules — so native-client masking follows Administration →
	// PII edits without a redeploy. Falls back to the static PIIOverlay env when the fetch fails.
	PIIOverlayURL         string // GET endpoint, e.g. https://app/api/v1/data-studio/studio/native-access/pii-overlay
	PIIOverlayToken       string // bearer token for the fetch (defaults to SKYBRIDGE_TOKEN)
	PIIOverlayPollSeconds int    // refresh interval in seconds (0 → default 60; <0 → fetch once)

	// Credential handoff / injection (design "skybridge-go-wire-proxy" §7 phase 3). When enabled the
	// agent terminates the native client's login locally (the client presents an opaque curlix
	// session token as its password instead of a database credential), exchanges that token with the
	// control plane for a freshly-minted upstream credential, and originates its own upstream auth.
	// The client therefore never holds a credential the database would accept directly. Disabled by
	// default: the agent forwards the client's auth verbatim, as before.
	InjectCredentials       bool   // SKYBRIDGE_INJECT_CREDENTIALS
	CredentialExchangeURL   string // SKYBRIDGE_CREDENTIAL_EXCHANGE_URL (POST endpoint on the control plane)
	CredentialExchangeToken string // bearer for the exchange call (defaults to SKYBRIDGE_TOKEN)

	// Client-side TLS termination (Postgres). When a cert+key is provided (or a self-signed cert is
	// requested) the agent accepts the native client's SSLRequest and completes a TLS handshake, so
	// the startup handshake and the injected-credential session token travel encrypted instead of in
	// the client's cleartext password. Off by default: SSL is declined and the client link is plaintext.
	ClientTLSCertPEM    []byte // SKYBRIDGE_CLIENT_TLS_CERT_PEM / _FILE
	ClientTLSKeyPEM     []byte // SKYBRIDGE_CLIENT_TLS_KEY_PEM / _FILE
	ClientTLSSelfSigned bool   // SKYBRIDGE_CLIENT_TLS_SELF_SIGNED (dev: generate an ephemeral cert at startup)

	// Upstream (agent → database) TLS (Postgres). When the mode is a TLS mode the agent negotiates
	// SSL with the upstream after dialing (SSLRequest → 'S' → handshake), so the agent→DB hop is
	// encrypted. Required for rds_iam injection (the IAM token is only accepted over TLS). Modes
	// mirror libpq sslmode: disable (default) | prefer | require | verify-ca | verify-full.
	UpstreamTLSMode       string // SKYBRIDGE_UPSTREAM_TLS
	UpstreamTLSCAPEM      []byte // SKYBRIDGE_UPSTREAM_TLS_CA_PEM / _FILE (trust roots for verify-* modes)
	UpstreamTLSServerName string // SKYBRIDGE_UPSTREAM_TLS_SERVER_NAME (override the verified hostname/SNI)
}

Agent is the resolved configuration for an egress-side Skybridge agent.

func LoadAgent

func LoadAgent() Agent

LoadAgent reads the agent config from the environment, applying defaults.

func (Agent) ClientTLSConfigured

func (a Agent) ClientTLSConfigured() bool

ClientTLSConfigured reports whether client-side TLS termination should be enabled.

func (Agent) TargetByName

func (a Agent) TargetByName(name string) (tunnel.Target, bool)

TargetByName returns the configured target with the given name.

func (Agent) UpstreamTLSEnabled

func (a Agent) UpstreamTLSEnabled() bool

UpstreamTLSEnabled reports whether the agent should negotiate TLS to the upstream database.

type ClientListener

type ClientListener struct {
	Addr   string `json:"addr"`
	Target string `json:"target"`
}

ClientListener binds a local listen address to a registered target name.

type Edge

type Edge struct {
	// Call-home transport (always on when GatewayAddr is set).
	GatewayAddr string // Connector Gateway endpoint host:port (dialed OUT)
	TenantID    string // organization id this edge serves
	EdgeID      string // stable edge instance id
	Token       string // bearer token (when not using mTLS)
	Insecure    bool   // plaintext channel (dev only)

	// mTLS (hardened call-home). When CABundle is set the edge uses mTLS (enrolling if needed);
	// otherwise it falls back to bearer-token-over-TLS using Token.
	CABundle     []byte // CA bundle trusted for the gateway (enables mTLS)
	TLSDir       string // directory holding/persisting ca.pem, client.crt, client.key
	EnrollTarget string // Enroll endpoint host:port (defaults to GatewayAddr)
	EnrollToken  string // one-time enrollment token
	TrustDomain  string // SPIFFE trust domain placed in the CSR SAN (cosmetic)

	// Live read-only AWS access (executed locally at the edge).
	AWSRegion        string
	AWSAssumeRoleARN string
	AWSExternalID    string
	AWSBinary        string

	// Studio execution agent (Query Studio dispatch — curlix.studiogateway.v1 on :7200).
	StudioGateway         string // SKYBRIDGE_STUDIO_GATEWAY host:port
	StudioEnrollGateway   string // SKYBRIDGE_STUDIO_ENROLL_GATEWAY (defaults to StudioGateway)
	StudioEnrollmentToken string
	StudioAgentID         string
	StudioMaxSessions     int
	StudioTargetsJSON     string
	StudioDBUser          string
	StudioDBPassword      string
	StudioTLSDir          string
	StudioTrustDomain     string

	// Optional co-located wire proxy. When non-empty the edge also runs the DB proxy (see Agent).
	WireProxy Agent
}

Edge is the resolved configuration for the unified edge binary. The edge runs the egress-only call-home transport (dialing OUT to the SaaS Connector Gateway) and, when DB targets are also configured, the co-located wire proxy — one process, one identity, for everything that must run inside the customer environment.

func LoadEdge

func LoadEdge() Edge

LoadEdge reads the unified edge config from the environment.

func (Edge) StudioEnabled

func (e Edge) StudioEnabled() bool

StudioEnabled reports whether the edge should dial the Studio Gateway (:7200).

func (Edge) WireProxyEnabled

func (e Edge) WireProxyEnabled() bool

WireProxyEnabled reports whether the edge should also run the co-located DB wire proxy.

type Gateway

type Gateway struct {
	AgentListen string           // address agents dial into (egress endpoint), e.g. ":8010"
	AuthToken   string           // required registration token (empty disables the check)
	Clients     []ClientListener // native-client listeners, each bound to a target

	// Session recording -> control plane (optional). When ControlPlaneURL is set the gateway reports
	// native-session lifecycle to the configured path; otherwise sessions are not recorded.
	ControlPlaneURL   string
	ControlPlaneToken string
	SessionPath       string // base path for session lifecycle reports (default /api/v1/data-studio/studio/native-sessions)
}

Gateway is the resolved configuration for the relay-side gateway.

func LoadGateway

func LoadGateway() Gateway

LoadGateway reads the gateway config from the environment.