cloudauth

package
v0.17.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 20, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Index

Constants

View Source
const (
	AuthorizationCapability   = "authorization"
	TypeAuthorizationSnapshot = "authorization.snapshot"
)
View Source
const (
	AuthorizationSnapshotFile = "authorization-snapshot.json"
	CloudKeysFile             = "cloud-jwks.json"
)

Files in Config.StateDir. Both belong to the registration that fetched them.

View Source
const DefaultCloudURL = "https://api.miren.cloud"

DefaultCloudURL is the default URL for miren.cloud

Variables

View Source
var ErrClusterNotRegistered = errors.New("cluster not registered with cloud")

ErrClusterNotRegistered reports that miren.cloud has no cluster for this service account. Unregistering is meant to be safe to retry, so callers treat this as "the cloud side is already done" rather than a failure.

View Source
var ErrDiscoveryUnavailable = errors.New("cloud workload identity discovery is unavailable")

ErrDiscoveryUnavailable reports that miren.cloud is not configured to anchor workload identity. Nothing the cluster can do about it, so callers keep their existing anchor rather than retrying into a wall.

View Source
var ErrPrivateAddress = errors.New("client IP is not a public address")

ErrPrivateAddress is returned when the cloud rejects the request because the cluster's IP is private/loopback/link-local.

Functions

func PublicKeyFromPEM

func PublicKeyFromPEM(pemData string) (crypto.PublicKey, error)

PublicKeyFromPEM parses a public key from PEM format

func VerifySignature

func VerifySignature(publicKey ed25519.PublicKey, message []byte, signatureBase64 string) bool

VerifySignature verifies a signature against the public key

Types

type AuthClient

type AuthClient struct {
	// contains filtered or unexported fields
}

AuthClient handles service account authentication with miren.cloud

func NewAuthClient

func NewAuthClient(serverURL string, keyPair *KeyPair) (*AuthClient, error)

NewAuthClient creates a new authentication client

func (*AuthClient) Authenticate

func (a *AuthClient) Authenticate(ctx context.Context) (string, error)

Authenticate performs the public key authentication flow and returns a JWT

func (*AuthClient) GetToken

func (a *AuthClient) GetToken(ctx context.Context) (string, error)

GetToken returns a valid JWT, refreshing if necessary

func (*AuthClient) InvalidateToken

func (a *AuthClient) InvalidateToken()

InvalidateToken clears the cached token

func (*AuthClient) PublishJWKS added in v0.14.0

func (a *AuthClient) PublishJWKS(ctx context.Context, jwksDocument []byte) (*PublishJWKSResult, error)

PublishJWKS sends the public half of this cluster's workload identity signing keys to miren.cloud, which serves them as OIDC discovery on the cluster's behalf.

The private keys never leave this machine and cloud never sees them: it holds the anchor and the public material, so a compromise there cannot mint an identity. What cloud provides in exchange is a stable, publicly reachable discovery endpoint, which is what lets a cluster behind NAT federate to AWS or GCP at all and keeps federation working while the cluster is down.

The document is the cluster's complete current key set. Cloud treats it as authoritative and stops serving anything absent from it, which is the whole of the rotation protocol: rotate locally, publish, done.

func (*AuthClient) UnregisterSelf added in v0.14.0

func (a *AuthClient) UnregisterSelf(ctx context.Context) error

UnregisterSelf asks miren.cloud to remove the cluster this client authenticates as, revoking its service account along the way. It is the cloud half of `miren server unregister` — the cluster identifies itself with the service account key from its registration, so no user login is involved.

type AuthorizationLink interface {
	OfferCapability(uplink.CapabilityOffer)
	OnSession(func(context.Context, uplink.Session))
	Handle(string, uplink.MessageHandler)
}

type AuthorizationSnapshot added in v0.17.0

type AuthorizationSnapshot struct {
	SessionID      string              `json:"session_id"`
	OrganizationID string              `json:"organization_id"`
	Revision       uint64              `json:"revision"`
	Policy         rbac.Policy         `json:"policy"`
	Memberships    map[string][]string `json:"memberships"`
}

AuthorizationSnapshot is the version 1 cloud authorization contract. Cloud sends full replacements, with increasing revisions within each session. Revisions restart with each session, so they only order snapshots within one.

func (*AuthorizationSnapshot) GetPolicy added in v0.17.0

func (s *AuthorizationSnapshot) GetPolicy() *rbac.Policy

type AuthorizationState added in v0.17.0

type AuthorizationState struct {
	// contains filtered or unexported fields
}

AuthorizationState serializes snapshot replacement with evaluation, including cache reads/writes. Clearing a cache alone would allow an in-flight old-policy evaluation to repopulate it after a revocation.

Cloud defines access, so the last snapshot it sent stays authoritative until it sends another. Losing the connection, reconnecting, or restarting is not new information about permissions, and neither is an update we cannot read, so none of them withdraw access. The cost is that a demotion made while the cluster cannot hear cloud waits for the next snapshot to take effect.

func NewAuthorizationState added in v0.17.0

func NewAuthorizationState(ctx context.Context, logger *slog.Logger, path, clusterID string) *AuthorizationState

NewAuthorizationState restores the snapshot saved at path for clusterID, if any, and saves each applied snapshot there. An empty path keeps the snapshot in memory only.

func (*AuthorizationState) Evaluate added in v0.17.0

func (s *AuthorizationState) Evaluate(req *rbac.Request) (rbac.Decision, string)

func (*AuthorizationState) Register added in v0.17.0

func (s *AuthorizationState) Register(link AuthorizationLink)

type BeginAuthRequest

type BeginAuthRequest struct {
	Fingerprint string `json:"fingerprint"`
}

BeginAuthRequest is the request to begin authentication

type BeginAuthResponse

type BeginAuthResponse struct {
	Envelope  string `json:"envelope"`
	Challenge string `json:"challenge"`
}

BeginAuthResponse is the response from begin authentication

type CompleteAuthRequest

type CompleteAuthRequest struct {
	Envelope  string `json:"envelope"`
	Signature string `json:"signature"`
}

CompleteAuthRequest is the request to complete authentication

type CompleteAuthResponse

type CompleteAuthResponse struct {
	ServiceAccount struct {
		ID   string `json:"id"`
		Name string `json:"name"`
	} `json:"service_account"`
	Token     string `json:"token"`
	ExpiresIn int    `json:"expires_in,omitempty"` // Optional: seconds until expiry
}

CompleteAuthResponse is the response from complete authentication

type Config

type Config struct {
	CloudURL string
	Logger   *slog.Logger
	Tags     map[string]any // Tags for this runtime/cluster
	// ClusterID is the cloud cluster this registration created. Saved
	// authorization state is tied to it, so a server registered again never
	// restores another registration's permissions.
	ClusterID string
	// StateDir holds cloud's last authorization snapshot and signing keys, so a
	// restart while cloud is unreachable keeps admitting cloud users. Empty, or
	// no ClusterID, keeps both in memory only.
	StateDir string
}

Config for RPCAuthenticator

func (*Config) Validate

func (c *Config) Validate() error

Validate validates the configuration

type KeyPair

type KeyPair struct {
	PrivateKey ed25519.PrivateKey
	PublicKey  ed25519.PublicKey
}

KeyPair represents an ED25519 key pair for cluster authentication

func GenerateKeyPair

func GenerateKeyPair() (*KeyPair, error)

GenerateKeyPair generates a new ED25519 key pair

func LoadKeyPairFromPEM

func LoadKeyPairFromPEM(privateKeyPEM string) (*KeyPair, error)

LoadKeyPairFromPEM loads a key pair from PEM encoded strings

func (*KeyPair) Fingerprint

func (kp *KeyPair) Fingerprint() string

Fingerprint returns the SHA256 fingerprint of the public key in the format "SHA256:base64encoded" to match the server

func (*KeyPair) PrivateKeyPEM

func (kp *KeyPair) PrivateKeyPEM() (string, error)

PrivateKeyPEM returns the private key in PEM format

func (*KeyPair) PublicKeyPEM

func (kp *KeyPair) PublicKeyPEM() (string, error)

PublicKeyPEM returns the public key in PEM format

func (*KeyPair) Sign

func (kp *KeyPair) Sign(message []byte) (string, error)

Sign signs a message with the private key

type NetcheckDualStackResult added in v0.7.0

type NetcheckDualStackResult struct {
	IPv4 *NetcheckResponse
	IPv6 *NetcheckResponse
}

NetcheckDualStackResult holds netcheck responses for both address families.

func NetcheckDualStack added in v0.7.0

func NetcheckDualStack(ctx context.Context, cloudURL string, ports []NetcheckPort) (*NetcheckDualStackResult, error)

NetcheckDualStack calls the netcheck endpoint concurrently over IPv4 and IPv6 to discover public addresses on both address families. Each call gets its own timeout so a missing address family fails fast without blocking the other. Either result may be nil if the address family is unavailable or the check fails. Returns an error only if both checks fail.

func (*NetcheckDualStackResult) ReachabilityVerdict added in v0.12.0

func (r *NetcheckDualStackResult) ReachabilityVerdict() *ReachabilityVerdict

ReachabilityVerdict synthesizes a compact reachability verdict from a netcheck result, for reporting to cloud. It returns nil when netcheck produced no usable public source address for either family (nil result, missing responses, or a private/invalid source) — in that case there is nothing proven to report and cloud should fall back to its generic copy.

When a public source address is present, the verdict names it. If any port on that source was reachable, Reachable is true and no ports are listed; otherwise Reachable is false and every failed port is listed with its transport so the dashboard can say "UDP 8443 (QUIC) unreachable".

type NetcheckPort added in v0.6.1

type NetcheckPort struct {
	Port     int    `json:"port"`
	Protocol string `json:"protocol"` // "http", "https", "http3"
}

NetcheckPort describes a port and protocol to check for reachability.

type NetcheckRequest added in v0.6.1

type NetcheckRequest struct {
	Ports []NetcheckPort `json:"ports"`
}

NetcheckRequest is the request body for the netcheck endpoint.

type NetcheckResponse added in v0.6.1

type NetcheckResponse struct {
	SourceAddress string           `json:"source_address"`
	Results       []NetcheckResult `json:"results"`
	DurationMs    int              `json:"duration_ms"`
}

NetcheckResponse is the response from the netcheck endpoint.

func Netcheck added in v0.6.1

func Netcheck(ctx context.Context, cloudURL string, ports []NetcheckPort, network string) (*NetcheckResponse, error)

Netcheck calls the cloud's netcheck endpoint to determine whether the cluster is publicly reachable on the given ports. The endpoint requires no authentication — it uses the request's source IP for probing.

The network parameter controls the address family: "tcp4" forces IPv4, "tcp6" forces IPv6, and "" uses the OS default.

type NetcheckResult added in v0.6.1

type NetcheckResult struct {
	Port      int    `json:"port"`
	Protocol  string `json:"protocol"`
	Reachable bool   `json:"reachable"`
	LatencyMs int    `json:"latency_ms"`
	Error     string `json:"error,omitempty"`
}

NetcheckResult is the result of a single port check.

type PolicyFetcher

type PolicyFetcher struct {
	// contains filtered or unexported fields
}

PolicyFetcher is a one-shot HTTP policy reader for the offline debug CLI. Running clusters authorize from AuthorizationState, never this endpoint.

func NewPolicyFetcher

func NewPolicyFetcher(cloudURL string, authClient *AuthClient) *PolicyFetcher

func (*PolicyFetcher) Fetch

func (pf *PolicyFetcher) Fetch(ctx context.Context) error

func (*PolicyFetcher) GetPolicy

func (pf *PolicyFetcher) GetPolicy() *rbac.Policy

type PublishJWKSResult added in v0.14.0

type PublishJWKSResult struct {
	Issuer   string `json:"issuer"`
	JWKSURI  string `json:"jwks_uri"`
	KeyCount int    `json:"key_count"`
}

PublishJWKSResult is where miren.cloud has anchored this cluster's workload identity — the iss claim its tokens should carry and the URL verifiers will fetch keys from.

type RPCAuthenticator

type RPCAuthenticator struct {
	// contains filtered or unexported fields
}

RPCAuthenticator adapts cloud authentication for RPC usage

func NewRPCAuthenticator

func NewRPCAuthenticator(ctx context.Context, config Config) (*RPCAuthenticator, error)

NewRPCAuthenticator creates a new RPC authenticator

func (*RPCAuthenticator) Authenticate added in v0.3.1

func (a *RPCAuthenticator) Authenticate(ctx context.Context, creds *rpc.Credentials) (*rpc.Identity, error)

Authenticate implements rpc.Authenticator. It tries JWT authentication first, then falls back to TLS client certificate. Authorization (RBAC) is handled separately via the Authorize method.

func (*RPCAuthenticator) Authorize added in v0.3.1

func (a *RPCAuthenticator) Authorize(ctx context.Context, identity *rpc.Identity, resource, action string) error

Authorize implements rpc.Authorizer. It performs RBAC evaluation to determine if the identity can perform the action.

func (*RPCAuthenticator) RegisterAuthorization added in v0.17.0

func (a *RPCAuthenticator) RegisterAuthorization(link AuthorizationLink)

RegisterAuthorization binds cloud authorization to the shared uplink.

func (*RPCAuthenticator) Stop

func (a *RPCAuthenticator) Stop()

Stop stops background tasks

type ReachabilityVerdict added in v0.12.0

type ReachabilityVerdict struct {
	// Reachable is true when netcheck confirmed at least one reachable port
	// on a public source address. Deliberately no omitempty: a false value is
	// the interesting case and must travel on the wire.
	Reachable bool `json:"reachable"`
	// PublicAddress is the public source address netcheck observed (the IP the
	// cluster appears as from the internet), e.g. "159.195.16.123".
	PublicAddress string `json:"public_address,omitempty"`
	// UnreachablePorts lists the ports that failed the check, present only
	// when Reachable is false.
	UnreachablePorts []UnreachablePort `json:"unreachable_ports,omitempty"`
}

ReachabilityVerdict is a compact, agent-computed explanation of the cluster's inbound reachability, synthesized from the netcheck trace at report time. It exists so the dashboard can name the culprit ("found 159.195.16.123 but UDP 8443 (QUIC) unreachable") instead of showing a generic "Not reachable" with static guess-at-the-fix copy.

type UnreachablePort added in v0.12.0

type UnreachablePort struct {
	Port      int    `json:"port"`
	Protocol  string `json:"protocol"`  // "http3", "https", "http"
	Transport string `json:"transport"` // "UDP" (QUIC/http3) or "TCP"
}

UnreachablePort names a single port/protocol that netcheck could not reach, with its transport spelled out so the dashboard can say "UDP 8443 (QUIC)".

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL