Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-18579-proof-failure-reason.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- **A calendar email whose proof mail was refused now says why** under **Settings, Meeting attendee, My calendar emails**, instead of only "pending": the reason in plain words with what to do (not authenticated by the sender's mail server, sent from a different address, naming the From address hive-mx saw, or the code expired), when it arrived, and the SPF, DKIM and alignment results hive-mx saw (results and domains only, never the message), with a **Check again** button. The calendar-emails API carries the same summary as `last_failure`. A proof mail whose code matches no address shows, sender masked, under the owner's **Recent proof attempts** (`recent_proof_attempts`, owner only). ([#18579](https://github.com/hivecommons/hive/issues/18579))
16 changes: 12 additions & 4 deletions dashboard/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -807,7 +807,7 @@
"Meetings"
],
"summary": "List my calendar emails",
"description": "The signed-in user's calendar email addresses with proof status and pending codes, the hive's address (hive@<host>) and the meetings.email switches. ?all=1 adds the whole allowlist for the owner. Any role.",
"description": "The signed-in user's calendar email addresses with proof status and pending codes, the hive's address (hive@<host>) and the meetings.email switches. An unproven address whose latest proof mail was refused carries last_failure. The owner also gets recent_proof_attempts (proof mails whose code matched no address, sender masked). ?all=1 adds the whole allowlist for the owner. Any role.",
"parameters": [
{
"name": "all",
Expand All @@ -834,21 +834,29 @@
"type": "array",
"items": {
"type": "object",
"description": "Calendar email: email, proven, proven_at, code (pending proof code, own list only), code_expires_at, last_error, active (the user still has access), login (owner allowlist only)"
"description": "Calendar email: email, proven, proven_at, code (pending proof code, own list only), code_expires_at, last_error, active (the user still has access), login (owner allowlist only), last_failure (latest refused proof: reason not_aligned, from_mismatch or expired; at; from (from_mismatch only: the From address parsed, empty when missing, repeated or unparsable); from_domain, spf, spf_domain, spf_aligned, dkim [{domain, result}], dkim_aligned, dmarc, aligned; message, the reason in plain words with what to do)"
}
},
"allowlist": {
"type": "array",
"items": {
"type": "object",
"description": "Calendar email: email, proven, proven_at, code (pending proof code, own list only), code_expires_at, last_error, active (the user still has access), login (owner allowlist only)"
"description": "Calendar email: email, proven, proven_at, code (pending proof code, own list only), code_expires_at, last_error, active (the user still has access), login (owner allowlist only), last_failure (latest refused proof: reason not_aligned, from_mismatch or expired; at; from (from_mismatch only: the From address parsed, empty when missing, repeated or unparsable); from_domain, spf, spf_domain, spf_aligned, dkim [{domain, result}], dkim_aligned, dmarc, aligned; message, the reason in plain words with what to do)"
}
},
"invites_enabled": {
"type": "boolean"
},
"files_enabled": {
"type": "boolean"
},
"recent_proof_attempts": {
"type": "array",
"description": "Owner only: recent proof mails whose code matched no address, newest first; kept in memory",
"items": {
"type": "object",
"description": "Proof attempt: at, from (masked, a***@example.com), reason (code not recognized)"
}
}
}
}
Expand Down Expand Up @@ -897,7 +905,7 @@
"properties": {
"email": {
"type": "object",
"description": "Calendar email: email, proven, proven_at, code (pending proof code, own list only), code_expires_at, last_error, active (the user still has access), login (owner allowlist only)"
"description": "Calendar email: email, proven, proven_at, code (pending proof code, own list only), code_expires_at, last_error, active (the user still has access), login (owner allowlist only), last_failure (latest refused proof: reason not_aligned, from_mismatch or expired; at; from (from_mismatch only: the From address parsed, empty when missing, repeated or unparsable); from_domain, spf, spf_domain, spf_aligned, dkim [{domain, result}], dkim_aligned, dmarc, aligned; message, the reason in plain words with what to do)"
},
"address": {
"type": "string"
Expand Down
4 changes: 2 additions & 2 deletions src/docs/api-reference/knowledge.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `POST` | `/api/meetings/persona/sample` | Owner or read-write | Speak a short line through the meetings TTS service (Kokoro `POST /v1/audio/speech`) and return the audio (`audio/mpeg`, at most 2 MiB, `Cache-Control: no-store`). Optional `{voice?, language?, display_name?, text?}` (unsaved form values; `text` at most 200 characters, default the persona's sample line in its language). 503 "TTS not configured" until `meetings.tts_url` is set, 400 invalid, 502 the TTS service failed | `pkg/dashboard/api_meetings_persona.go:166` |
| `GET` | `/api/meetings/persona/sample` | Owner or read-write | The same sample with `voice`, `language`, `display_name` and `text` as query parameters, for the dashboard's `<audio>` element (the dashboard CSP has no `media-src`, so audio must come from the dashboard origin) | `pkg/dashboard/api_meetings_persona.go:169` |
| `POST` | `/api/meetings/invites` | Hub relay signature | Calendar invites hive-mx received for `hive@<host>` ([#18395](https://github.com/hivecommons/hive/issues/18395)), relayed by the hub with `X-Hive-Relay-Timestamp`, `X-Hive-Relay-Signature-256` and `X-Hive-Relay-Delivery` (5-minute skew, replay-protected). An invite is scheduled at once when the sender is its organizer, passed DMARC alignment and is on the calendar email allowlist, otherwise it awaits approval; a change or CANCEL for a meeting already on the calendar applies only when authenticated as its organizer. `200 {results[]}`; `409` invites or meetings off; `422` nothing schedulable; `401` bad relay signature. See [Inviting Betty by email](../meetings.md#inviting-betty-by-email) | `pkg/dashboard/api_meetings_email.go:62` |
| `POST` | `/api/meetings/calendar-emails/proof` | Hub relay signature | A proof mail: the address whose pending code is in the subject is proven when the mail came from it and passed DMARC alignment. `200 {proven, email}`; `422` unknown or expired code, or not authenticated for that address (the failure is shown on the address) | `pkg/dashboard/api_meetings_email.go:63` |
| `GET` | `/api/meetings/calendar-emails` | Any role | The signed-in user's calendar emails (`email`, `proven`, `proven_at`, pending `code` and `code_expires_at`, `last_error`, `active`), the hive's `address` and the `invites_enabled` / `files_enabled` switches; `?all=1` adds the whole `allowlist` for the owner (no codes) | `pkg/dashboard/api_meetings_email.go:64` |
| `POST` | `/api/meetings/calendar-emails/proof` | Hub relay signature | A proof mail: the address whose pending code is in the subject is proven when the mail came from it and passed DMARC alignment. `200 {proven, email}`; `422` unknown code (shown, sender masked, in the owner's `recent_proof_attempts`), or an expired code, another sender or no DMARC alignment for that address (the reason and SPF/DKIM/alignment summary are recorded on the address as `last_failure`) | `pkg/dashboard/api_meetings_email.go:63` |
| `GET` | `/api/meetings/calendar-emails` | Any role | The signed-in user's calendar emails (`email`, `proven`, `proven_at`, pending `code` and `code_expires_at`, `last_error`, `last_failure` with the refused proof's `reason` (`not_aligned`, `from_mismatch`, `expired`), `at`, the parsed From `from` on a mismatch, SPF/DKIM/alignment results and plain-language `message`, `active`), the hive's `address` and the `invites_enabled` / `files_enabled` switches; the owner also gets `recent_proof_attempts` (unknown-code proof mails, sender masked); `?all=1` adds the whole `allowlist` for the owner (no codes) | `pkg/dashboard/api_meetings_email.go:64` |
| `POST` | `/api/meetings/calendar-emails` | Any role | Register `{email}` for the signed-in user: `201 {email, address, instruction}` with a proof code valid for 24 hours and the instruction to send a mail from that address to `hive@<host>` with the code in the subject. At most 10 per user. Audited as `calendar-email-add` | `pkg/dashboard/api_meetings_email.go:65` |
| `DELETE` | `/api/meetings/calendar-emails` | Any role | Remove `?email=` from the signed-in user's list; the owner may add `&login=` to remove another user's. Audited as `calendar-email-remove` | `pkg/dashboard/api_meetings_email.go:66` |
12 changes: 12 additions & 0 deletions src/docs/meetings.md
Original file line number Diff line number Diff line change
Expand Up @@ -194,6 +194,18 @@ An update to a meeting already on the calendar (a higher SEQUENCE, or a cancella

Each user registers the addresses their calendar sends invites from, under **Settings, Meeting attendee** (API: `/api/meetings/calendar-emails`). Adding an address shows a proof code such as `hive-proof-k7f3qz2mwx4a` and the instruction: send an email from that address to `hive@<host>` with this code in the subject. When that mail arrives with DMARC alignment for exactly that address, the address is marked proven. A proof mail from another address, or one that fails DMARC, is recorded on the address so the user can see why. Codes are valid for 24 hours and can be reissued; each user can register 10 addresses. Hive never sends mail, so this is how it learns which addresses are yours.

When a proof mail does not count, the address stays pending and its row says why, in plain words, within a few seconds of the mail arriving ([#18579](https://github.com/hivecommons/hive/issues/18579)):

| Reason | What the row says |
| --- | --- |
| `not_aligned` | Your mail server did not authenticate this address: neither SPF nor DKIM passed for the domain. Turn on DKIM for the domain, add the sending server to SPF, or prove an address from a provider that signs mail. |
| `from_mismatch` | The proof came from a different address than the one registered, and names the From address hive-mx parsed, or "(none: the From header was missing, repeated or unparsable)" when there was no single readable From. |
| `expired` | The code expired. Remove and add the address again. |

The row also shows when the attempt arrived and what hive-mx saw: the SPF result and domain, each DKIM signature's result and domain, and whether either was aligned with the From domain (DMARC alignment: the domain that passed SPF or DKIM must match the From address's domain). Only these results and domains are kept, never the message. **Check again** reloads the list after you fix it and resend. In the API, an unproven address carries `last_failure` with `reason`, `at`, `from` (on `from_mismatch` only: the From address seen, shown in full because the address is the user's own entry), `from_domain`, `spf`, `spf_domain`, `spf_aligned`, `dkim`, `dkim_aligned`, `dmarc`, `aligned` and `message`.

A proof mail whose code matches no address (a typo, or a code already used) has no row to land on. The owner sees it under **Recent proof attempts** in the same section (API: `recent_proof_attempts`, owner only) with the sender masked (`a***@example.com`), the time and "code not recognized". Hive keeps the latest 20 in memory; a restart clears them.

## Asking Betty to do things

People in the meeting can ask Betty, spoken or typed in the meeting chat, to draft something in the hive ([#18406](https://github.com/hivecommons/hive/issues/18406)):
Expand Down
60 changes: 57 additions & 3 deletions src/pkg/dashboard/api_meetings_email.go
Original file line number Diff line number Diff line change
Expand Up @@ -182,13 +182,20 @@ func (s *Server) handleCalendarEmailProof(w http.ResponseWriter, r *http.Request
jsonError(w, "calendar emails are not available on this hive", http.StatusConflict)
return
}
e, err := st.Prove(d.Proof.Code, d.Auth.From, d.Auth.Aligned)
e, err := st.ProveAuth(d.Proof.Code, d.Auth)
switch {
case err == nil:
s.webhookLogger().Info("calendar email proven", "delivery", d.ID)
jsonResponse(w, map[string]any{"proven": true, "email": e.Email})
case errors.Is(err, mailallow.ErrUnknownCode), errors.Is(err, mailallow.ErrNotProven):
// Permanent: the sender's server bounces it, which tells the user.
// Permanent: the sender's server bounces it. The reason is also on
// the entry (Settings row) or, for an unknown code, in the owner's
// recent proof attempts (#18579).
reason := mailallow.AttemptCodeNotRecognized
if e.LastFailure != nil {
reason = e.LastFailure.Reason
}
s.webhookLogger().Info("calendar email proof refused", "delivery", d.ID, "reason", reason)
jsonError(w, err.Error(), http.StatusUnprocessableEntity)
default:
jsonError(w, "could not record the proof", http.StatusInternalServerError)
Expand Down Expand Up @@ -235,13 +242,54 @@ type calendarEmailView struct {
Code string `json:"code,omitempty"`
CodeExpiresAt *time.Time `json:"code_expires_at,omitempty"`
LastError string `json:"last_error,omitempty"`
// LastFailure is the latest failed proof: reason code, time, the SPF,
// DKIM and alignment results, and Message, the plain-language reason
// with what to do (#18579).
LastFailure *calendarEmailFailureView `json:"last_failure,omitempty"`
// Active is false when the user no longer has access to this hive: the
// address is then not on the effective allowlist.
Active bool `json:"active"`
}

// calendarEmailFailureView is a failed proof as the Settings row shows it.
type calendarEmailFailureView struct {
mailallow.ProofFailure
Message string `json:"message"`
}

// proofFromNone stands in for the From address of a from-mismatch proof
// whose From header the receiver could not read as one address.
const proofFromNone = "(none: the From header was missing, repeated or unparsable)"

// proofFailureMessage says in plain words why a proof of email failed and
// what to do about it.
func proofFailureMessage(f mailallow.ProofFailure, email string) string {
switch f.Reason {
case mailallow.ReasonCodeNotAligned:
domain := f.FromDomain
if domain == "" {
domain = email[strings.LastIndexByte(email, '@')+1:]
}
return "Your mail server did not authenticate this address: neither SPF nor DKIM passed for " + domain +
". Turn on DKIM for the domain, add the sending server to SPF, or prove an address from a provider that signs mail."
case mailallow.ReasonCodeFromMismatch:
seen := f.From
if seen == "" {
seen = proofFromNone
}
return "The proof came from a different address than the one registered: the mail's From was " + seen + ". Send it from " + email + " itself."
case mailallow.ReasonCodeExpired:
return "The code expired. Remove and add the address again."
default:
return "The proof mail did not count. Send it again."
}
}

func (s *Server) calendarEmailView(e mailallow.Entry, withLogin bool) calendarEmailView {
v := calendarEmailView{Email: e.Email, Proven: e.Proven(), ProvenAt: e.ProvenAt, Code: e.Code, LastError: e.LastError, Active: s.hasMailAccess(e.Login)}
if f := e.LastFailure; f != nil && !e.Proven() {
v.LastFailure = &calendarEmailFailureView{ProofFailure: *f, Message: proofFailureMessage(*f, e.Email)}
}
if e.Code != "" {
t := e.CodeExpiresAt
v.CodeExpiresAt = &t
Expand Down Expand Up @@ -286,7 +334,13 @@ func (s *Server) handleCalendarEmailsList(w http.ResponseWriter, r *http.Request
"invites_enabled": em.InvitesOn(),
"files_enabled": em.FilesOn(),
}
if r.URL.Query().Get("all") == "1" && isOwnerRole(r.Header.Get("X-Hive-Role")) {
owner := isOwnerRole(r.Header.Get("X-Hive-Role"))
if owner {
// Proof mails whose code matched nothing (a typo), masked: the
// owner's view of the hive's mail activity (#18579).
out["recent_proof_attempts"] = st.RecentAttempts()
}
if r.URL.Query().Get("all") == "1" && owner {
all := []calendarEmailView{}
for _, e := range st.All() {
all = append(all, s.calendarEmailView(e, true))
Expand Down
Loading
Loading