Documentation
¶
Index ¶
- Constants
- Variables
- func PublicKeyFromPEM(pemData string) (crypto.PublicKey, error)
- func VerifySignature(publicKey ed25519.PublicKey, message []byte, signatureBase64 string) bool
- type AuthClient
- func (a *AuthClient) Authenticate(ctx context.Context) (string, error)
- func (a *AuthClient) GetToken(ctx context.Context) (string, error)
- func (a *AuthClient) InvalidateToken()
- func (a *AuthClient) PublishJWKS(ctx context.Context, jwksDocument []byte) (*PublishJWKSResult, error)
- func (a *AuthClient) UnregisterSelf(ctx context.Context) error
- type AuthorizationLink
- type AuthorizationSnapshot
- type AuthorizationState
- func (s *AuthorizationState) AllowsLegacy(req *rbac.Request) bool
- func (s *AuthorizationState) Evaluate(req *rbac.Request) (rbac.Decision, string)
- func (s *AuthorizationState) EvaluateMethod(req *rbac.Request, migrated bool) (rbac.Decision, string)
- func (s *AuthorizationState) EvaluateResource(req *rbac.Request, legacyResource, legacyAction string) (rbac.Decision, string)
- func (s *AuthorizationState) Register(link AuthorizationLink)
- type BeginAuthRequest
- type BeginAuthResponse
- type CompleteAuthRequest
- type CompleteAuthResponse
- type Config
- type KeyPair
- type NetcheckDualStackResult
- type NetcheckPort
- type NetcheckRequest
- type NetcheckResponse
- type NetcheckResult
- type PolicyFetcher
- type PublishJWKSResult
- type RPCAuthenticator
- func (a *RPCAuthenticator) Authenticate(ctx context.Context, creds *rpc.Credentials) (*rpc.Identity, error)
- func (a *RPCAuthenticator) Authorize(ctx context.Context, identity *rpc.Identity, resource, action string) error
- func (a *RPCAuthenticator) AuthorizeResource(ctx context.Context, identity *rpc.Identity, request rpc.ResourceRequest) error
- func (a *RPCAuthenticator) RegisterAuthorization(link AuthorizationLink)
- func (a *RPCAuthenticator) Stop()
- func (a *RPCAuthenticator) UsesLogicalAuthorization(ctx context.Context, identity *rpc.Identity) bool
- type ReachabilityVerdict
- type UnreachablePort
Constants ¶
const ( AuthorizationCapability = "authorization" TypeAuthorizationSnapshot = "authorization.snapshot" )
const ( AuthorizationSnapshotFile = "authorization-snapshot.json" CloudKeysFile = "cloud-jwks.json" )
Files in Config.StateDir. Both belong to the registration that fetched them.
const DefaultCloudURL = "https://api.miren.cloud"
DefaultCloudURL is the default URL for miren.cloud
Variables ¶
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.
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.
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 ¶
PublicKeyFromPEM parses a public key from PEM format
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 ¶ added in v0.17.0
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 {
// Version 2 selects logical resource permissions. Zero preserves saved and
// wire version-1 snapshots, whose permissions name RPC interfaces/methods.
Version uint `json:"version,omitempty"`
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 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) AllowsLegacy ¶ added in v0.18.0
func (s *AuthorizationState) AllowsLegacy(req *rbac.Request) bool
AllowsLegacy authorizes before permitting a handler to skip logical checks. A version-only read could skip both gates during a v2-to-v1 transition.
func (*AuthorizationState) EvaluateMethod ¶ added in v0.18.0
func (s *AuthorizationState) EvaluateMethod(req *rbac.Request, migrated bool) (rbac.Decision, string)
EvaluateMethod defers migrated methods only under logical policy. Legacy method authorization and the version decision share the snapshot lock.
func (*AuthorizationState) EvaluateResource ¶ added in v0.18.0
func (s *AuthorizationState) EvaluateResource(req *rbac.Request, legacyResource, legacyAction string) (rbac.Decision, string)
EvaluateResource selects legacy or logical vocabulary under the same lock as snapshot replacement. A revocation cannot race a separate version lookup.
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
type KeyPair ¶
type KeyPair struct {
PrivateKey ed25519.PrivateKey
PublicKey ed25519.PublicKey
}
KeyPair represents an ED25519 key pair for cluster authentication
func GenerateKeyPair ¶
GenerateKeyPair generates a new ED25519 key pair
func LoadKeyPairFromPEM ¶
LoadKeyPairFromPEM loads a key pair from PEM encoded strings
func (*KeyPair) Fingerprint ¶
Fingerprint returns the SHA256 fingerprint of the public key in the format "SHA256:base64encoded" to match the server
func (*KeyPair) PrivateKeyPEM ¶
PrivateKeyPEM returns the private key in PEM format
func (*KeyPair) PublicKeyPEM ¶
PublicKeyPEM returns the public key in PEM format
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) 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) AuthorizeResource ¶ added in v0.18.0
func (a *RPCAuthenticator) AuthorizeResource(ctx context.Context, identity *rpc.Identity, request rpc.ResourceRequest) error
func (*RPCAuthenticator) RegisterAuthorization ¶ added in v0.17.0
func (a *RPCAuthenticator) RegisterAuthorization(link AuthorizationLink)
RegisterAuthorization binds cloud authorization to the shared uplink.
func (*RPCAuthenticator) UsesLogicalAuthorization ¶ added in v0.18.0
func (a *RPCAuthenticator) UsesLogicalAuthorization(ctx context.Context, identity *rpc.Identity) bool
UsesLogicalAuthorization permits the legacy path only after evaluating its original method under the same lock as the policy version. Denied or unsynced legacy callers still reach the resource gate, which returns their denial.
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)".