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 ¶
- func AllowsEmail(ctx context.Context, q *storegen.Queries, log *slog.Logger, userID uuid.UUID, ...) bool
- func Defaults(userID uuid.UUID) storegen.UserNotificationSetting
- func EmailAllowed(row storegen.UserNotificationSetting, kind Kind) bool
- func EmailPermitted(verified bool, row storegen.UserNotificationSetting, kind Kind) bool
- func Settings(ctx context.Context, q *storegen.Queries, userID uuid.UUID) (storegen.UserNotificationSetting, error)
- type AccessRequestNotice
- type AccountNotice
- type AccountNoticeKind
- type AdvisoryNotice
- type InviteOffer
- type Kind
- type Links
- type LogNotifier
- func (n LogNotifier) AccountChanged(_ context.Context, notice AccountNotice) error
- func (n LogNotifier) AdvisoryPublished(_ context.Context, notice AdvisoryNotice) error
- func (n LogNotifier) AgentQuarantined(_ context.Context, notice QuarantineNotice) error
- func (n LogNotifier) EmailVerification(_ context.Context, toEmail, _, token string) error
- func (n LogNotifier) MCPDependencyAlert(_ context.Context, notice MCPDependencyAlertNotice) error
- func (n LogNotifier) OrgAccessRequest(_ context.Context, notice AccessRequestNotice) error
- func (n LogNotifier) OrgInvite(_ context.Context, notice InviteOffer) error
- func (n LogNotifier) OrgPendingMembers(_ context.Context, notice PendingMembersNotice) error
- func (n LogNotifier) Rendered(_ context.Context, notice RenderedNotice) error
- func (n LogNotifier) ReviewDecided(_ context.Context, notice ReviewNotice) error
- type MCPDependencyAlertNotice
- type Notifier
- type Options
- type PendingMember
- type PendingMembersNotice
- type QuarantineNotice
- type RenderedNotice
- type ReviewNotice
- type SMTPNotifier
- func (n *SMTPNotifier) AccountChanged(ctx context.Context, notice AccountNotice) error
- func (n *SMTPNotifier) AdvisoryPublished(ctx context.Context, notice AdvisoryNotice) error
- func (n *SMTPNotifier) AgentQuarantined(ctx context.Context, notice QuarantineNotice) error
- func (n *SMTPNotifier) EmailVerification(ctx context.Context, toEmail, handle, token string) error
- func (n *SMTPNotifier) MCPDependencyAlert(ctx context.Context, notice MCPDependencyAlertNotice) error
- func (n *SMTPNotifier) OrgAccessRequest(ctx context.Context, notice AccessRequestNotice) error
- func (n *SMTPNotifier) OrgInvite(ctx context.Context, notice InviteOffer) error
- func (n *SMTPNotifier) OrgPendingMembers(ctx context.Context, notice PendingMembersNotice) error
- func (n *SMTPNotifier) Rendered(ctx context.Context, notice RenderedNotice) error
- func (n *SMTPNotifier) ReviewDecided(ctx context.Context, notice ReviewNotice) error
- type SMTPOptions
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.
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 ¶
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 ¶
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.
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.