Documentation
¶
Overview ¶
Package dashboard provides an embedded web UI for the config-server gateway. It serves static files from the embedded filesystem and relies on the existing HTTP REST endpoints for all data operations.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Handler ¶
func Handler(mountPath, apiBase string, auth DashboardAuth) http.Handler
Handler returns an HTTP handler serving the dashboard UI at the given mount path (e.g. "/dashboard"). The path must start with "/" and should not end with "/"; if empty, "/dashboard" is used.
apiBase is the base path prefix used by the dashboard JS when constructing API URLs (e.g. "" for same-origin, "/api" for a proxied deployment). The value is injected into the page via the "api-base" meta tag.
auth, if non-nil, is applied in two ways:
- auth.Middleware wraps the handler so unauthenticated requests are rejected before the static files are served.
- auth.ClientConfig() is JSON-encoded and injected into index.html as the text content of the "auth-config" script tag so the dashboard JS knows how to attach credentials to every config API request it makes.
Pass nil for auth to serve the dashboard without any access control (suitable when the route is protected at the network or reverse-proxy level).
Types ¶
type DashboardAuth ¶
type DashboardAuth interface {
// Middleware returns an HTTP handler that enforces authentication.
// Unauthenticated requests must not be forwarded to next; respond
// with an appropriate status (typically 401) instead.
Middleware(next http.Handler) http.Handler
// ClientConfig returns the key→value pairs that are JSON-encoded and
// injected into index.html as the "auth-config" meta tag content.
//
// Keys recognised by the built-in JS:
// "auth-type" — "cookie", "bearer", or "none"
// "auth-credentials" — fetch credentials mode ("include", "same-origin")
// "auth-header" — request header name for bearer auth
ClientConfig() map[string]string
}
DashboardAuth protects the dashboard route and configures the embedded JS to authenticate every config API request it makes.
The two concerns are deliberately coupled: whatever credential the server accepts on the dashboard route (a session cookie, a JWT cookie, a bearer token) is the same credential the browser forwards to the config REST API, so the SecurityGuard on the gRPC service validates the same credential on both paths.
Server side: Middleware wraps the static file handler; unauthenticated requests are rejected before they reach it.
Client side: ClientConfig returns key→value pairs that are JSON-encoded and injected into index.html as the "auth-config" meta tag. The dashboard JS reads this to decide how to attach credentials to each fetch call.
Built-in implementations are provided for the two most common cases:
- CookieAuth / CookieAuth with a JWT validator — the browser forwards the cookie automatically; no token input is shown.
- BearerTokenAuth — the dashboard shows a persistent token input field in the sidebar; the token is kept in sessionStorage.
For any other strategy (e.g. mTLS, HTTP Basic, custom header) implement this interface directly.
func BearerTokenAuth ¶
func BearerTokenAuth(validate func(r *http.Request, token string) error) DashboardAuth
BearerTokenAuth returns a DashboardAuth that expects an "Authorization: Bearer <token>" header on every dashboard request. validate receives the raw token without the "Bearer " prefix; return a non-nil error to reject with 401. validate may be nil, in which case any non-empty token is accepted.
The dashboard JS shows a persistent token-input field in the sidebar. The token is stored in sessionStorage (current tab only) and attached as an Authorization header to every config API request.
func CookieAuth ¶
func CookieAuth(cookieName string, validate func(r *http.Request, cookieValue string) error) DashboardAuth
CookieAuth returns a DashboardAuth that reads cookieName from the request cookie jar and calls validate with the raw value. validate may be nil, in which case any non-empty cookie is accepted.
Because the browser forwards cookies automatically on same-origin requests, the dashboard JS is configured with credentials:"include" and no token-input UI is shown to the user. This covers both plain session cookies and JWT cookies — the validation logic lives entirely in validate.
func HMACAuth ¶
func HMACAuth(cfg HMACConfig) (DashboardAuth, error)
HMACAuth returns a fully self-contained DashboardAuth that:
- Serves an inline login form at <mountPath><LoginPath>.
- Validates the submitted passphrase with constant-time comparison.
- Issues a stateless, HMAC-SHA256-signed session cookie on success; no session store is required.
- Rejects requests with missing or invalid cookies by redirecting to the login page.
From the JS side the session behaves identically to CookieAuth — ClientConfig returns {"auth-type":"cookie","auth-credentials":"include"}.
This handler does not throttle login attempts. Deploy behind a rate-limiter or reverse proxy to prevent brute-force attacks on the passphrase.
Returns an error if Secret is shorter than 32 bytes, Passphrase is empty, or LoginPath does not start with "/".
type HMACConfig ¶
type HMACConfig struct {
// Secret is the HMAC-SHA256 signing key for session tokens.
// Must be at least 32 bytes. Load from an environment variable or secrets
// manager — never hard-code in source.
Secret []byte
// Passphrase is the shared login passphrase validated on the login form.
// Load from an environment variable — never hard-code in source.
Passphrase string
// CookieName is the session cookie name. Default: "dash-session".
CookieName string
// TokenTTL is how long a session token remains valid. Default: 8h.
// Set to 0 for non-expiring tokens (not recommended for production).
TokenTTL time.Duration
// LoginPath is the path suffix (relative to the dashboard mount) for the
// login page. Default: "/login".
// If the dashboard is mounted at "/dashboard", the login page is at
// "/dashboard/login".
LoginPath string
// Secure sets the Secure flag on the session cookie.
// Should be true in production (requires HTTPS).
Secure bool
}
HMACConfig configures the HMAC-based dashboard auth.
Source Files