SPB Git

Repository Public

apns.go 16.4 KB 634 lines go

1// Package notify delivers alert notifications to the owner's devices.2//3// This file implements an Apple Push Notification service (APNs) HTTP/24// provider using token-based (JWT ES256) authentication. When no signing key5// is configured the provider reports itself inactive instead of failing.6package notify78import (9	"bytes"10	"context"11	"crypto/ecdsa"12	"crypto/elliptic"13	"crypto/rand"14	"crypto/sha256"15	"crypto/tls"16	"crypto/x509"17	"encoding/base64"18	"encoding/json"19	"encoding/pem"20	"errors"21	"fmt"22	"io"23	"net/http"24	"net/netip"25	"net/url"26	"os"27	"strconv"28	"strings"29	"sync"30	"time"31)3233const (34	defaultProductionURL = "https://api.push.apple.com"35	defaultSandboxURL    = "https://api.sandbox.push.apple.com"3637	// Apple rejects provider tokens older than one hour and rate-limits38	// regeneration to once per 20 minutes: renew in between.39	tokenMaxAge = 50 * time.Minute4041	maxAttempts     = 342	baseBackoff     = 500 * time.Millisecond43	maxResponseBody = 4 << 1044	pushTTL         = time.Hour45	maxNodeAliasLen = 6446	threadID        = "mcc-alerts"47	redacted        = "[redacted]"48)4950// APNsConfig comes from env (MCC_APNS_KEY_FILE, MCC_APNS_KEY_ID,51// MCC_APNS_TEAM_ID, MCC_APNS_TOPIC_IOS, MCC_APNS_TOPIC_MACOS).52type APNsConfig struct {53	KeyFile    string // path of the .p8 (PKCS#8 PEM, EC P-256) token signing key54	KeyID      string55	TeamID     string56	TopicIOS   string // bundle id of the iOS app57	TopicMacOS string // bundle id of the macOS app5859	// Test hooks; zero values = Apple's hosts and a default HTTP/2 client60	// with sane timeouts.61	ProductionURL string // default "https://api.push.apple.com"62	SandboxURL    string // default "https://api.sandbox.push.apple.com"63	HTTPClient    *http.Client64	Now           func() time.Time65	Sleep         func(context.Context, time.Duration) error // backoff between retries66}6768// Push is everything a notification may contain. Deliberately tiny: NO69// command, secret, IP address, hostname other than the node alias, metric70// value or log line can be expressed.71type Push struct {72	DeviceToken string // hex APNs token73	Env         string // "development" (sandbox host) | "production"74	DeviceKind  string // "ios" | "macos" -> selects the topic75	AlertID     string // uuid76	Severity    string // info | warning | critical77	NodeAlias   string // may be empty78	State       string // "firing" | "resolved"79}8081// Outcome is the result of one Send.82type Outcome string8384const (85	Sent         Outcome = "sent"86	InvalidToken Outcome = "invalid_token" // caller must forget this device token87	Failed       Outcome = "failed"        // gave up after bounded retries, or permanent provider error88	Inactive     Outcome = "inactive"      // provider not configured (or no topic for this device kind)89)9091// Status is a snapshot of the provider health, safe to expose over an API:92// it never contains key material, provider tokens or device tokens.93type Status struct {94	State         string     `json:"state"`            // inactive | active | degraded (last attempt failed)95	Reason        string     `json:"reason,omitempty"` // why inactive/degraded96	LastSuccessAt *time.Time `json:"last_success_at,omitempty"`97	LastErrorAt   *time.Time `json:"last_error_at,omitempty"`98	LastError     string     `json:"last_error,omitempty"`99	Sent          int64      `json:"sent"`100	Failed        int64      `json:"failed"`101	Invalidated   int64      `json:"invalidated"`102}103104// APNs is an APNs HTTP/2 provider. Safe for concurrent use.105type APNs struct {106	cfg    APNsConfig107	key    *ecdsa.PrivateKey108	client *http.Client109	now    func() time.Time110	sleep  func(context.Context, time.Duration) error111112	active         bool113	inactiveReason string114115	mu          sync.Mutex116	jwt         string117	jwtAt       time.Time118	degraded    bool119	lastSuccess time.Time120	lastErrorAt time.Time121	lastError   string122	sent        int64123	failed      int64124	invalidated int64125}126127// NewAPNs never fails: incomplete configuration, unreadable or invalid key128// => an inactive provider whose Status explains why.129func NewAPNs(cfg APNsConfig) *APNs {130	a := &APNs{cfg: cfg, client: cfg.HTTPClient, now: cfg.Now, sleep: cfg.Sleep}131	if a.now == nil {132		a.now = time.Now133	}134	if a.sleep == nil {135		a.sleep = sleepCtx136	}137	if a.client == nil {138		a.client = defaultHTTPClient()139	}140	if a.cfg.ProductionURL == "" {141		a.cfg.ProductionURL = defaultProductionURL142	}143	if a.cfg.SandboxURL == "" {144		a.cfg.SandboxURL = defaultSandboxURL145	}146	a.cfg.ProductionURL = strings.TrimRight(a.cfg.ProductionURL, "/")147	a.cfg.SandboxURL = strings.TrimRight(a.cfg.SandboxURL, "/")148149	var missing []string150	if cfg.KeyFile == "" {151		missing = append(missing, "MCC_APNS_KEY_FILE")152	}153	if cfg.KeyID == "" {154		missing = append(missing, "MCC_APNS_KEY_ID")155	}156	if cfg.TeamID == "" {157		missing = append(missing, "MCC_APNS_TEAM_ID")158	}159	if cfg.TopicIOS == "" && cfg.TopicMacOS == "" {160		missing = append(missing, "MCC_APNS_TOPIC_IOS or MCC_APNS_TOPIC_MACOS")161	}162	if len(missing) > 0 {163		a.inactiveReason = "not configured: missing " + strings.Join(missing, ", ")164		return a165	}166167	key, reason := loadSigningKey(cfg.KeyFile)168	if key == nil {169		a.inactiveReason = reason170		return a171	}172	a.key = key173	a.active = true174	return a175}176177// loadSigningKey reads a PKCS#8 PEM EC P-256 key. The returned reason never178// contains file content.179func loadSigningKey(path string) (*ecdsa.PrivateKey, string) {180	raw, err := os.ReadFile(path)181	if err != nil {182		switch {183		case errors.Is(err, os.ErrNotExist):184			return nil, "signing key file not found"185		case errors.Is(err, os.ErrPermission):186			return nil, "signing key file not readable (permission denied)"187		default:188			return nil, "signing key file unreadable"189		}190	}191	block, _ := pem.Decode(raw)192	if block == nil {193		return nil, "signing key file is not PEM"194	}195	parsed, err := x509.ParsePKCS8PrivateKey(block.Bytes)196	if err != nil {197		return nil, "signing key is not a valid PKCS#8 private key"198	}199	key, ok := parsed.(*ecdsa.PrivateKey)200	if !ok || key.Curve != elliptic.P256() {201		return nil, "signing key is not an EC P-256 key"202	}203	return key, ""204}205206func defaultHTTPClient() *http.Client {207	return &http.Client{208		Timeout: 20 * time.Second,209		Transport: &http.Transport{210			Proxy:                 http.ProxyFromEnvironment,211			ForceAttemptHTTP2:     true,212			TLSClientConfig:       &tls.Config{MinVersion: tls.VersionTLS12},213			TLSHandshakeTimeout:   10 * time.Second,214			ResponseHeaderTimeout: 15 * time.Second,215			IdleConnTimeout:       90 * time.Second,216			MaxIdleConnsPerHost:   2,217		},218	}219}220221func sleepCtx(ctx context.Context, d time.Duration) error {222	t := time.NewTimer(d)223	defer t.Stop()224	select {225	case <-ctx.Done():226		return ctx.Err()227	case <-t.C:228		return nil229	}230}231232// Active reports whether the provider is configured and able to send.233func (a *APNs) Active() bool { return a.active }234235// Status returns a snapshot of the provider health. Safe for concurrent use.236func (a *APNs) Status() Status {237	if !a.active {238		return Status{State: "inactive", Reason: a.inactiveReason}239	}240	a.mu.Lock()241	defer a.mu.Unlock()242	s := Status{243		State:       "active",244		LastError:   a.lastError,245		Sent:        a.sent,246		Failed:      a.failed,247		Invalidated: a.invalidated,248	}249	if a.degraded {250		s.State = "degraded"251		s.Reason = a.lastError252	}253	if !a.lastSuccess.IsZero() {254		t := a.lastSuccess255		s.LastSuccessAt = &t256	}257	if !a.lastErrorAt.IsZero() {258		t := a.lastErrorAt259		s.LastErrorAt = &t260	}261	return s262}263264// Send pushes one alert notification. The error is non-nil only with Failed.265func (a *APNs) Send(ctx context.Context, p Push) (Outcome, error) {266	if !a.active {267		return Inactive, nil268	}269	var topic string270	switch p.DeviceKind {271	case "ios":272		topic = a.cfg.TopicIOS273	case "macos":274		topic = a.cfg.TopicMacOS275	}276	if topic == "" {277		return Inactive, nil278	}279	if !validDeviceToken(p.DeviceToken) {280		a.recordInvalid(false)281		return InvalidToken, nil282	}283	if !validAlertID(p.AlertID) {284		return a.fail(errors.New("apns: alert id is not a UUID"), false)285	}286	var base string287	switch p.Env {288	case "production":289		base = a.cfg.ProductionURL290	case "development", "sandbox":291		base = a.cfg.SandboxURL292	default:293		return a.fail(errors.New("apns: unknown device environment"), false)294	}295296	endpoint := base + "/3/device/" + p.DeviceToken297	body := BuildPayload(p)298	priority := "5"299	if normSeverity(p.Severity) == "critical" && normState(p.State) == "firing" {300		priority = "10"301	}302303	renewed := false304	attempt := 1305	for {306		jwt, err := a.token()307		if err != nil {308			return a.fail(errors.New("apns: cannot sign provider token"), true)309		}310		status, reason, err := a.do(ctx, endpoint, jwt, topic, priority, p.AlertID, body)311312		var lastErr error313		switch {314		case err != nil:315			lastErr = fmt.Errorf("apns: transport error: %s", scrub(err, p.DeviceToken, jwt))316		case status == http.StatusOK:317			a.recordSuccess()318			return Sent, nil319		case status == http.StatusGone,320			status == http.StatusBadRequest && isInvalidTokenReason(reason):321			a.recordInvalid(true)322			return InvalidToken, nil323		case status == http.StatusForbidden && reason == "ExpiredProviderToken" && !renewed:324			renewed = true325			a.dropToken(jwt)326			if ctx.Err() != nil {327				return a.fail(fmt.Errorf("apns: %s", scrub(ctx.Err(), p.DeviceToken, jwt)), true)328			}329			continue330		case status == http.StatusTooManyRequests || status >= 500:331			lastErr = statusError(status, reason)332		default:333			return a.fail(statusError(status, reason), true)334		}335336		if ctx.Err() != nil || attempt >= maxAttempts {337			return a.fail(fmt.Errorf("%w (gave up after %d attempt(s))", lastErr, attempt), true)338		}339		if err := a.sleep(ctx, baseBackoff<<(attempt-1)); err != nil {340			return a.fail(fmt.Errorf("%w (gave up after %d attempt(s))", lastErr, attempt), true)341		}342		attempt++343	}344}345346// do performs one HTTP exchange and returns the status and APNs reason.347func (a *APNs) do(ctx context.Context, endpoint, jwt, topic, priority, collapseID string, body []byte) (int, string, error) {348	req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, bytes.NewReader(body))349	if err != nil {350		return 0, "", errors.New("cannot build request")351	}352	req.Header.Set("authorization", "bearer "+jwt)353	req.Header.Set("content-type", "application/json")354	req.Header.Set("apns-topic", topic)355	req.Header.Set("apns-push-type", "alert")356	req.Header.Set("apns-priority", priority)357	req.Header.Set("apns-expiration", strconv.FormatInt(a.now().Add(pushTTL).Unix(), 10))358	req.Header.Set("apns-collapse-id", collapseID)359360	resp, err := a.client.Do(req)361	if err != nil {362		return 0, "", err363	}364	defer resp.Body.Close()365	raw, _ := io.ReadAll(io.LimitReader(resp.Body, maxResponseBody))366	var parsed struct {367		Reason string `json:"reason"`368	}369	_ = json.Unmarshal(raw, &parsed)370	return resp.StatusCode, cleanReason(parsed.Reason), nil371}372373// token returns the cached provider token, signing a new one when needed.374func (a *APNs) token() (string, error) {375	a.mu.Lock()376	defer a.mu.Unlock()377	now := a.now()378	if a.jwt != "" {379		if age := now.Sub(a.jwtAt); age >= 0 && age < tokenMaxAge {380			return a.jwt, nil381		}382	}383	jwt, err := signProviderToken(a.key, a.cfg.KeyID, a.cfg.TeamID, now)384	if err != nil {385		return "", err386	}387	a.jwt, a.jwtAt = jwt, now388	return jwt, nil389}390391// dropToken forgets the cached token if it is still the rejected one.392func (a *APNs) dropToken(rejected string) {393	a.mu.Lock()394	if a.jwt == rejected {395		a.jwt = ""396	}397	a.mu.Unlock()398}399400func signProviderToken(key *ecdsa.PrivateKey, keyID, teamID string, now time.Time) (string, error) {401	header, err := json.Marshal(struct {402		Alg string `json:"alg"`403		Kid string `json:"kid"`404	}{"ES256", keyID})405	if err != nil {406		return "", err407	}408	claims, err := json.Marshal(struct {409		Iss string `json:"iss"`410		Iat int64  `json:"iat"`411	}{teamID, now.Unix()})412	if err != nil {413		return "", err414	}415	enc := base64.RawURLEncoding416	input := enc.EncodeToString(header) + "." + enc.EncodeToString(claims)417	digest := sha256.Sum256([]byte(input))418	r, s, err := ecdsa.Sign(rand.Reader, key, digest[:])419	if err != nil {420		return "", err421	}422	// JWS ES256 signature: fixed-width r||s, not ASN.1 DER.423	sig := make([]byte, 64)424	r.FillBytes(sig[:32])425	s.FillBytes(sig[32:])426	return input + "." + enc.EncodeToString(sig), nil427}428429func (a *APNs) recordSuccess() {430	a.mu.Lock()431	a.sent++432	a.lastSuccess = a.now()433	a.degraded = false434	a.mu.Unlock()435}436437// recordInvalid counts a rejected device token. reachedProvider tells whether438// APNs itself answered (which proves the provider works).439func (a *APNs) recordInvalid(reachedProvider bool) {440	a.mu.Lock()441	a.invalidated++442	if reachedProvider {443		a.degraded = false444	}445	a.mu.Unlock()446}447448// fail records a failure; degrade marks the provider itself as unhealthy (as449// opposed to a bad request from the caller).450func (a *APNs) fail(err error, degrade bool) (Outcome, error) {451	a.mu.Lock()452	a.failed++453	a.lastErrorAt = a.now()454	a.lastError = err.Error()455	if degrade {456		a.degraded = true457	}458	a.mu.Unlock()459	return Failed, err460}461462func statusError(status int, reason string) error {463	if reason == "" {464		return fmt.Errorf("apns: HTTP %d", status)465	}466	return fmt.Errorf("apns: HTTP %d %s", status, reason)467}468469// scrub renders an error without the request URL (which embeds the device470// token) and masks any stray secret.471func scrub(err error, secrets ...string) string {472	var uerr *url.Error473	if errors.As(err, &uerr) && uerr.Err != nil {474		err = uerr.Err475	}476	msg := err.Error()477	for _, s := range secrets {478		if s != "" {479			msg = strings.ReplaceAll(msg, s, redacted)480		}481	}482	if len(msg) > 200 {483		msg = msg[:200] + "..."484	}485	return msg486}487488// cleanReason keeps only a short alphanumeric APNs reason code.489func cleanReason(s string) string {490	var b strings.Builder491	for _, r := range s {492		if b.Len() >= 64 {493			break494		}495		if (r >= 'A' && r <= 'Z') || (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') {496			b.WriteRune(r)497		}498	}499	return b.String()500}501502func isInvalidTokenReason(reason string) bool {503	switch reason {504	case "BadDeviceToken", "DeviceTokenNotForTopic", "Unregistered":505		return true506	}507	return false508}509510func validDeviceToken(tok string) bool {511	if len(tok) < 32 || len(tok) > 200 || len(tok)%2 != 0 {512		return false513	}514	for i := 0; i < len(tok); i++ {515		if !isHex(tok[i]) {516			return false517		}518	}519	return true520}521522func validAlertID(id string) bool {523	if len(id) != 36 {524		return false525	}526	for i := 0; i < len(id); i++ {527		if id[i] != '-' && !isHex(id[i]) {528			return false529		}530	}531	return true532}533534func isHex(c byte) bool {535	return (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F')536}537538func normSeverity(s string) string {539	switch s {540	case "info", "warning", "critical":541		return s542	}543	return "info"544}545546func normState(s string) string {547	switch s {548	case "firing", "resolved":549		return s550	}551	return "firing"552}553554// sanitizeNodeAlias returns the alias (at most 64 chars of [A-Za-z0-9._-]).555// An alias containing any other character, or one that is an IP address, is556// treated as hostile and dropped entirely rather than partially kept, so that557// fragments of it (e.g. an address) cannot leak into a notification.558func sanitizeNodeAlias(s string) string {559	for i := 0; i < len(s); i++ {560		c := s[i]561		ok := (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') ||562			c == '.' || c == '_' || c == '-'563		if !ok {564			return ""565		}566	}567	if len(s) > maxNodeAliasLen {568		s = s[:maxNodeAliasLen]569	}570	if _, err := netip.ParseAddr(s); err == nil {571		return ""572	}573	return s574}575576type apsAlert struct {577	Title string `json:"title"`578	Body  string `json:"body"`579}580581type apsBlock struct {582	Alert    apsAlert `json:"alert"`583	Sound    string   `json:"sound,omitempty"`584	ThreadID string   `json:"thread-id"`585}586587type payload struct {588	APS      apsBlock `json:"aps"`589	AlertID  string   `json:"alert_id"`590	Severity string   `json:"severity"`591	Node     string   `json:"node,omitempty"`592	State    string   `json:"state"`593}594595// BuildPayload returns the exact JSON body sent to APNs.596func BuildPayload(p Push) []byte {597	severity := normSeverity(p.Severity)598	state := normState(p.State)599	node := sanitizeNodeAlias(p.NodeAlias)600	alertID := p.AlertID601	if !validAlertID(alertID) {602		alertID = ""603	}604605	title := "MacLustr — " + severity + " alert"606	if state == "resolved" {607		title = "MacLustr — alert resolved"608	}609	subject := node610	if subject == "" {611		subject = "Cluster"612	}613	body := subject + " · " + severity614	if state == "resolved" {615		body += " · resolved"616	}617618	pl := payload{619		APS:      apsBlock{Alert: apsAlert{Title: title, Body: body}, ThreadID: threadID},620		AlertID:  alertID,621		Severity: severity,622		Node:     node,623		State:    state,624	}625	if state == "firing" && severity == "critical" {626		pl.APS.Sound = "default"627	}628	out, err := json.Marshal(pl)629	if err != nil { // unreachable: only strings630		return []byte(`{"aps":{"thread-id":"` + threadID + `"}}`)631	}632	return out633}634
Files main
Menu

Theme