notify

package
v0.7.9-dev.2 Latest Latest
Warning

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

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

Documentation

Overview

Package notify sends user-facing notifications (email in v1).

Two implementations: LogNotifier (the default — a fresh install says what it would have sent rather than pretending to send it) and SMTPNotifier, which speaks to mailpit on :1025 in the compose dev stack and to SES's SMTP endpoint on AWS.

No notification goes to an address the registry has not verified: every sender asks AllowsEmail (prefs.go) first, which refuses a user without users.email_verified_at before it reads a single preference. The verification mail is the one mail that does not ask, because it is how an address becomes verified.

Message bodies say what was found and what happens next. Nothing here calls an agent safe, secure, or verified — scanning reduces risk, it does not prove absence of it, and a notification is exactly where that overclaim would be most tempting and most damaging.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AllowsEmail

func AllowsEmail(ctx context.Context, q *storegen.Queries, log *slog.Logger, userID uuid.UUID, kind Kind) bool

AllowsEmail reports whether a mail of the given kind may go to the user. The two halves fail in opposite directions on purpose: a user row that cannot be read is treated as unverified (no mail — the address is the thing in doubt), while a settings row that cannot be read is treated as the defaults (mail — a broken preference read must not silence a security notice). A suppression for an unverified address is logged with the user id and the kind, never the address; a nil log means the default logger, as for the notifiers themselves.

func Defaults

func Defaults(userID uuid.UUID) storegen.UserNotificationSetting

Defaults is the settings row a user without one is treated as having: every mail on, except the two run kinds, which are off until the person turns them on.

func EmailAllowed

func EmailAllowed(row storegen.UserNotificationSetting, kind Kind) bool

EmailAllowed reports whether the row permits a mail of the given kind. Unknown kinds are allowed: a new mail class is opt-out, never lost.

func EmailPermitted

func EmailPermitted(verified bool, row storegen.UserNotificationSetting, kind Kind) bool

EmailPermitted is the whole decision for one mail: the address must be verified and the kind switched on. It is pure so the rule is testable without a database; AllowsEmail supplies the two facts.

func Settings

Settings loads a user's row, or the defaults when there is none.

Types

type AccessRequestNotice

type AccessRequestNotice struct {
	ToEmail string
	Org     string
	// OrgDisplayName is the organisation's name, for the sentence.
	OrgDisplayName string
	// Requester is the handle of the person asking; RequesterEmail their
	// verified address, which is at the organisation's domain.
	Requester      string
	RequesterEmail string
	// ConsoleURL is where the admin invites them; empty when the server
	// knows no absolute origin.
	ConsoleURL string
}

AccessRequestNotice is a request for access delivered to one of the organisation's admins.

type AccountNotice added in v0.6.1000

type AccountNotice struct {
	ToEmail string
	Handle  string
	Change  AccountNoticeKind
	// Removed is how many second factors were removed, for
	// AccountSecondFactorsRemoved.
	Removed int
}

AccountNotice is the mail for one staff act on an account.

type AccountNoticeKind added in v0.6.1000

type AccountNoticeKind string

AccountNoticeKind is what platform staff did to an account.

const (
	AccountSuspended  AccountNoticeKind = "suspended"
	AccountReinstated AccountNoticeKind = "reinstated"
	AccountSignedOut  AccountNoticeKind = "signed-out"
	// AccountSecondFactorsRemoved is second factors removed at the
	// person's directory; AccountNotice.Removed says how many.
	AccountSecondFactorsRemoved AccountNoticeKind = "second-factors-removed"
	// AccountErased is the account erased by platform staff.
	AccountErased AccountNoticeKind = "erased"
)

The acts AccountChanged tells of.

type AdvisoryNotice

type AdvisoryNotice struct {
	ToEmail  string
	Agent    string
	Severity string
	Summary  string
	// AffectedVersions is the range the advisory names, as stored — the
	// fact a consumer needs first.
	AffectedVersions string
	// AdvisoryURL is the public advisory page.
	AdvisoryURL string
}

AdvisoryNotice announces a published advisory.

type InviteOffer

type InviteOffer struct {
	ToEmail string
	Org     string
	// OrgDisplayName is the organisation's name, for the sentence.
	OrgDisplayName string
	// Role is the org role the invitation offers.
	Role string
	// InvitedBy is the inviting admin's handle.
	InvitedBy string
	// AcceptURL is where the recipient accepts it; empty when the server
	// knows no absolute origin, in which case the admin conveys the token.
	AcceptURL string
	// ExpiresAt is when the invitation stops working.
	ExpiresAt time.Time
}

InviteOffer offers a place in an organisation. An organisation's membership is offered and accepted, not granted, so the mail carries a link the person acts on and the role it names is not yet in force.

type Kind

type Kind string

Kind names one class of notification a person can switch off.

const (
	KindDependencyAlert Kind = "dependencyAlerts"
	KindQuarantine      Kind = "quarantine"
	KindReviewDecision  Kind = "reviewDecisions"
	KindAdvisory        Kind = "advisories"
	KindOrgInvite       Kind = "orgInvites"
	// KindBilling is the closed build's billing mail, sent through the
	// extension seam: a checkout confirmed, a payment
	// failed, an organization restricted, seats reached, "your
	// organization covers you". The core sends none itself; the kind is
	// here so the switch, the default and the rule are the core's.
	KindBilling Kind = "billing"
	// KindSchedule is the closed build's schedule mail, sent through the
	// extension seam: a
	// scheduled run in Agentry failed, or a schedule paused. Never a
	// success. The core sends none itself, as with billing.
	KindSchedule Kind = "schedules"
	// KindBugReport is the closed build's bug-report mail, sent through
	// the extension seam: platform
	// staff marked a bug report the person filed complete ("Reported bug
	// fixed"). The core sends none itself, as with billing.
	KindBugReport Kind = "bugReports"
	// KindRunFailure is the closed build's mail for a hosted run that
	// failed after it started or was refused by the queue: a run, a draft,
	// a knowledge build or a scheduled fire. Off by default: the hosted
	// service keeps the outcome, and mail about it is asked for.
	KindRunFailure Kind = "runFailures"
	// KindRunFinished is the closed build's mail for a hosted run that
	// completed. Off by default, like KindRunFailure.
	KindRunFinished Kind = "runFinished"
)
type Links struct {
	Dashboard   string
	VerifyEmail func(token string) string
	ReportCard  func(agent, version string) string
	// Settings is the page where a person switches these mails on and off:
	// the footer names it, so a reader knows where to go.
	Settings string
}

Links carries the resolved browser destinations for the renderer.

type LogNotifier

type LogNotifier struct {
	Log *slog.Logger
}

LogNotifier writes notifications to the log (dev/self-host default until SMTP is configured): that a mail would have gone, to which mailbox (the address masked, docs/logging.md), about what. Never the verification token — the log contract keeps every token out of every line, so an address cannot be verified through this notifier; that takes a sender.

func (LogNotifier) AccountChanged added in v0.6.1000

func (n LogNotifier) AccountChanged(_ context.Context, notice AccountNotice) error

AccountChanged implements Notifier.

func (LogNotifier) AdvisoryPublished

func (n LogNotifier) AdvisoryPublished(_ context.Context, notice AdvisoryNotice) error

AdvisoryPublished implements Notifier.

func (LogNotifier) AgentQuarantined

func (n LogNotifier) AgentQuarantined(_ context.Context, notice QuarantineNotice) error

AgentQuarantined implements Notifier. Logged at warn: on a self-host instance without SMTP this line is the only trace that an author was supposed to hear about a quarantine.

func (LogNotifier) EmailVerification

func (n LogNotifier) EmailVerification(_ context.Context, toEmail, _, token string) error

EmailVerification implements Notifier.

func (LogNotifier) MCPDependencyAlert

func (n LogNotifier) MCPDependencyAlert(_ context.Context, notice MCPDependencyAlertNotice) error

MCPDependencyAlert implements Notifier.

func (LogNotifier) OrgAccessRequest

func (n LogNotifier) OrgAccessRequest(_ context.Context, notice AccessRequestNotice) error

OrgAccessRequest implements Notifier.

func (LogNotifier) OrgInvite

func (n LogNotifier) OrgInvite(_ context.Context, notice InviteOffer) error

OrgInvite implements Notifier.

func (LogNotifier) OrgPendingMembers

func (n LogNotifier) OrgPendingMembers(_ context.Context, notice PendingMembersNotice) error

OrgPendingMembers implements Notifier.

func (LogNotifier) Rendered

func (n LogNotifier) Rendered(_ context.Context, notice RenderedNotice) error

Rendered implements Notifier.

func (LogNotifier) ReviewDecided

func (n LogNotifier) ReviewDecided(_ context.Context, notice ReviewNotice) error

ReviewDecided implements Notifier.

type MCPDependencyAlertNotice

type MCPDependencyAlertNotice struct {
	ToEmail string
	// Agent is "namespace/name"; Version the affected published version.
	Agent   string
	Version string
	// Server is the declared server, "npm:pkg@1.2.3" / "pypi:pkg@1.2.3".
	Server   string
	Severity string
	// Advisories are the advisory ids (GHSA/CVE) behind the alert.
	Advisories []string
	// FixedIn lists the server versions the advisories name as fixed.
	FixedIn []string
	// AgentURL points at the agent page.
	AgentURL string
}

MCPDependencyAlertNotice is a dependency alert delivered to the version's author.

type Notifier

type Notifier interface {
	// EmailVerification sends the address-confirmation (activation) message
	// for the account named handle. token is the one-time secret the user
	// posts back to /auth/verify-email. The mail names the account so that
	// someone who did not choose that name has a reason not to follow the
	// link: anyone can sign up with another person's address.
	EmailVerification(ctx context.Context, toEmail, handle, token string) error
	// AgentQuarantined tells an author that a version they published has been
	// pulled by a rescan (author notification is one of the three
	// notification paths, alongside the org webhook and the advisory).
	AgentQuarantined(ctx context.Context, n QuarantineNotice) error
	// ReviewDecided tells an author the outcome of a review.
	ReviewDecided(ctx context.Context, n ReviewNotice) error
	// AdvisoryPublished tells an author that an advisory naming their agent
	// is now public.
	AdvisoryPublished(ctx context.Context, n AdvisoryNotice) error
	// OrgInvite offers someone a place in an organisation. It is a real
	// offer with a link to accept, not a notice that a membership already
	// exists: nobody joins an organisation uninvited.
	OrgInvite(ctx context.Context, n InviteOffer) error
	// MCPDependencyAlert tells an author that a published version of theirs
	// declares an MCP server version with a newly known high or critical
	// vulnerability, and that the fix is a new version.
	MCPDependencyAlert(ctx context.Context, n MCPDependencyAlertNotice) error
	// OrgAccessRequest tells an organisation's admin that a person whose
	// verified address is at the organisation's domain asks to be added
	// One mail per admin, once a day per person.
	OrgAccessRequest(ctx context.Context, n AccessRequestNotice) error
	// OrgPendingMembers tells an organisation's admin who is waiting to be
	// approved: the people the domain folded in, and
	// the IdP provisioned, that no digest has named yet. One mail per
	// admin per organisation, batched daily; a person is named once.
	OrgPendingMembers(ctx context.Context, n PendingMembersNotice) error
	// Rendered delivers a message somebody else composed, in this
	// deployment's frame: the registry's name prefixed to the subject,
	// the text as the body exactly as given, the registry's footer with
	// the settings link beneath it. It exists for the extension seam: an
	// extension's billing mail is written there and carried here, so the
	// transport and the frame are the core's and its copy is not. kind
	// names the mail class in the log line, never the body.
	Rendered(ctx context.Context, n RenderedNotice) error
	// AccountChanged tells a person that platform staff changed their
	// account's access: suspended it, reinstated it, signed it out
	// everywhere, removed its second factors, or erased it. It is a security notice, sent whatever the person's
	// switches say, and only to a confirmed address.
	AccountChanged(ctx context.Context, n AccountNotice) error
}

Notifier delivers transactional notifications. Every method returns an error only for a delivery failure the caller could act on; callers treat notification failure as non-fatal to the state change that triggered it.

func New

func New(opt Options) (Notifier, error)

New builds the configured notifier.

type Options

type Options struct {
	// Kind is log | smtp. Empty means log.
	Kind string
	// BaseURL is the public origin, used to build links in message bodies.
	BaseURL string
	// Registry is the deployment's display name in message subjects.
	Registry string
	SMTP     SMTPOptions
	Log      *slog.Logger
	// Links are the browser destinations this deployment resolved:
	// Dashboard is where "see your dashboard" points; VerifyEmail builds the
	// address-verification link for a token; ReportCard builds the link to a
	// version's report card for "namespace/name" and a version.
	// Unset falls back to the site's own paths under BaseURL.
	Links Links
}

Options selects and configures the notifier.

type PendingMember

type PendingMember struct {
	Handle string
	// Email is their verified address.
	Email string
	// Via is the door: "domain" (their address is at the organisation's
	// domain) or "scim" (the organisation's IdP provisioned them).
	Via string
	// Since is when they became pending.
	Since time.Time
}

PendingMember is one person in the digest.

type PendingMembersNotice

type PendingMembersNotice struct {
	ToEmail string
	Org     string
	// OrgDisplayName is the organisation's name, for the sentence.
	OrgDisplayName string
	// Members are the people waiting, in the order they arrived.
	Members []PendingMember
	// ConsoleURL is where the admin approves or declines them; empty when
	// the server knows no absolute origin.
	ConsoleURL string
}

PendingMembersNotice is the daily digest delivered to one of the organisation's admins.

type QuarantineNotice

type QuarantineNotice struct {
	ToEmail string
	// Agent is "namespace/name".
	Agent    string
	Version  string
	Severity string
	Reason   string
	// ReportURL points at the full report, where the findings are shown to
	// someone the authorization check has already passed.
	ReportURL string
}

QuarantineNotice is what an author is told when a published version is quarantined. It deliberately carries no finding excerpts: the reason is a summary, and the detail lives on the report where it can be authorized.

type RenderedNotice

type RenderedNotice struct {
	ToEmail string
	Subject string
	// Text is the body, plain text, placed as given: no template runs
	// over it and nothing in it is interpreted, so nothing the composer
	// wrote can reach a header or the frame.
	Text string
	// Kind is the mail class for the log line and the preference switch.
	Kind Kind
}

RenderedNotice is a message composed outside the core, to be carried in the core's frame. Like every notice it is addressed by email, and like every notice the decision that the person may be written to — AllowsEmail, the verified address and the switch — is the caller's before it reaches the transport. What keeps an extension from skipping that decision is not this type but the seam: pkg/extension hands an extension Send(userID, …), never this transport or an address, and the one caller of Rendered is the core's own SendToUser, which decides first.

type ReviewNotice

type ReviewNotice struct {
	ToEmail string
	Agent   string
	Version string
	// Decision is the outcome the version reached: published | approved
	// (published moments later, by the registry's signer) | rejected |
	// yanked | needs_review. `yanked` arrives when a reviewer rejects an
	// already-quarantined version, which cannot go to `rejected` because that
	// edge does not exist (internal/api/handlers_reviews.go).
	Decision string
	// Reviewer is the deciding reviewer's handle, when the decision was made
	// by a human rather than by the automated gate.
	Reviewer string
	// Rationale is the reviewer's stated reason.
	Rationale string
	ReportURL string
}

ReviewNotice is a review verdict delivered to the version's author.

type SMTPNotifier

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

SMTPNotifier delivers notifications over SMTP. Point it at mailpit (:1025, no TLS, no auth) in dev, or at SES's SMTP endpoint on AWS — see docs/ops/deployment.md.

func NewSMTP

func NewSMTP(opt SMTPOptions, registry, baseURL string, log *slog.Logger) (*SMTPNotifier, error)

NewSMTP validates the configuration and builds the notifier. Address parsing happens here so a malformed From is a startup error rather than a delivery failure discovered the first time something goes wrong in production.

func (*SMTPNotifier) AccountChanged added in v0.6.1000

func (n *SMTPNotifier) AccountChanged(ctx context.Context, notice AccountNotice) error

AccountChanged implements Notifier.

func (*SMTPNotifier) AdvisoryPublished

func (n *SMTPNotifier) AdvisoryPublished(ctx context.Context, notice AdvisoryNotice) error

AdvisoryPublished implements Notifier.

func (*SMTPNotifier) AgentQuarantined

func (n *SMTPNotifier) AgentQuarantined(ctx context.Context, notice QuarantineNotice) error

AgentQuarantined implements Notifier.

func (*SMTPNotifier) EmailVerification

func (n *SMTPNotifier) EmailVerification(ctx context.Context, toEmail, handle, token string) error

EmailVerification implements Notifier.

func (*SMTPNotifier) MCPDependencyAlert

func (n *SMTPNotifier) MCPDependencyAlert(ctx context.Context, notice MCPDependencyAlertNotice) error

MCPDependencyAlert implements Notifier.

func (*SMTPNotifier) OrgAccessRequest

func (n *SMTPNotifier) OrgAccessRequest(ctx context.Context, notice AccessRequestNotice) error

OrgAccessRequest implements Notifier.

func (*SMTPNotifier) OrgInvite

func (n *SMTPNotifier) OrgInvite(ctx context.Context, notice InviteOffer) error

OrgInvite implements Notifier.

func (*SMTPNotifier) OrgPendingMembers

func (n *SMTPNotifier) OrgPendingMembers(ctx context.Context, notice PendingMembersNotice) error

OrgPendingMembers implements Notifier. A digest with nobody in it is not a mail; the caller never sends one, and this refuses it anyway.

func (*SMTPNotifier) Rendered

func (n *SMTPNotifier) Rendered(ctx context.Context, notice RenderedNotice) error

Rendered implements Notifier. The subject and the address are checked for header injection in compose like every other message's; the body is text and cannot carry a header.

func (*SMTPNotifier) ReviewDecided

func (n *SMTPNotifier) ReviewDecided(ctx context.Context, notice ReviewNotice) error

ReviewDecided implements Notifier.

type SMTPOptions

type SMTPOptions struct {
	Host     string
	Port     int
	Username string
	Password string
	// From is the envelope sender; it may be a bare address or a
	// "Name <addr>" form.
	From string
	// StartTLS upgrades the connection before AUTH.
	StartTLS bool
	// Timeout bounds one send end to end.
	Timeout time.Duration
}

SMTPOptions configures the SMTP transport.

Jump to

Keyboard shortcuts

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