push

package
v0.14.0 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package push tells a person's devices that an agent is waiting for them, so a permission request reaches the lock screen while no client is open.

Index

Constants

View Source
const (
	EnvSandbox    = "sandbox"
	EnvProduction = "production"
)

APNs environments: a build from Xcode gets sandbox tokens, a TestFlight or App Store build gets production ones, and each works only with its own Apple server.

Variables

View Source
var ErrBadDevice = errors.New("not an APNs device token and environment")

ErrBadDevice rejects a registration that cannot be an APNs device.

Functions

func LoadAPNsKey

func LoadAPNsKey(path string) (*ecdsa.PrivateKey, error)

LoadAPNsKey reads a token signing key (.p8) downloaded from the Apple Developer account.

func Retract

func Retract(ctx context.Context, notifiers []Notifier, m Message) error

Retract takes m back through the notifiers that can.

func Send

func Send(ctx context.Context, notifiers []Notifier, m Message) error

Send delivers m through every notifier at once, so a slow one does not hold up the others, and returns their errors joined.

Types

type APNs

type APNs struct {
	Key     *ecdsa.PrivateKey
	KeyID   string // the key's id in the developer account
	TeamID  string
	Topic   string // the app's bundle id
	Devices *DeviceStore
	// AllowedLogins are the logins whose devices still get alerts: a phone
	// whose login was removed from the allowlist gets nothing.
	AllowedLogins []string
	Client        *http.Client // must speak HTTP/2; Go's default client does over TLS
	// contains filtered or unexported fields
}

APNs sends alerts straight to Apple's push service with a token signing key (.p8) from the Apple Developer account, to every registered device.

func (*APNs) Notify

func (a *APNs) Notify(ctx context.Context, m Message) error

Notify sends m to every registered device. Devices Apple says are gone are forgotten; other failures are returned.

type Device

type Device struct {
	Token       string    `json:"token"` // lower-case hex
	Environment string    `json:"environment"`
	Login       string    `json:"login"` // the Tailscale login that registered it
	Added       time.Time `json:"added"`
}

Device is a phone that asked for approval notifications.

type DeviceStore

type DeviceStore struct {
	Path string
	// contains filtered or unexported fields
}

DeviceStore keeps registered devices in a JSON file, so they survive a restart of the server.

func (*DeviceStore) Add

func (s *DeviceStore) Add(d Device) error

Add registers d, replacing an earlier registration of the same token.

func (*DeviceStore) List

func (s *DeviceStore) List() ([]Device, error)

List returns the registered devices.

func (*DeviceStore) Remove

func (s *DeviceStore) Remove(token string) error

Remove forgets a token; an unknown one is not an error.

type Message

type Message struct {
	Title      string
	Body       string
	Link       string // opens the session in a client; optional
	ApprovalID string
	SessionID  string
	Expires    time.Time // not worth delivering after this; zero: deliver now or never
}

Message is one notification. It names what is asked (the tool call's title, which for a shell command is the command), never the tool's full input: a relay or the lock screen may show it to anyone.

func ForApproval

func ForApproval(sessionTitle, toolTitle string) Message

ForApproval words the notification for a permission request in a session. Both titles are shortened to fit about two lock-screen lines.

type Notifier

type Notifier interface {
	Notify(ctx context.Context, m Message) error
}

Notifier delivers a Message.

type Ntfy

type Ntfy struct {
	Server string // e.g. https://ntfy.sh
	Topic  string
	Token  string // access token for a protected topic; optional
	Client *http.Client
}

Ntfy publishes to an ntfy topic (ntfy.sh or a self-hosted server), which the ntfy phone app shows on the lock screen. Anyone who knows a topic on a public server can read it: use a hard-to-guess name or a token.

func (*Ntfy) Notify

func (n *Ntfy) Notify(ctx context.Context, m Message) error

Notify publishes m as JSON to the server root, so titles and bodies in any language survive (ntfy's header form is ASCII-only).

func (*Ntfy) Retract

func (n *Ntfy) Retract(ctx context.Context, m Message) error

Retract deletes the approval's notification from the topic, so a phone that was offline does not show it after the approval is resolved. The ntfy app removes it from the notification drawer too, where it can.

type Retracter

type Retracter interface {
	Retract(ctx context.Context, m Message) error
}

Retracter is a Notifier that can take back a notification once its approval is resolved, so a phone that was offline does not show it later.

Jump to

Keyboard shortcuts

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