Repository Public
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