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-18395-mail-in-files.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Mail Markdown, audio and image files to `hive@<your hive's host>` and they land in the Inbox as email items: from an allowlisted calendar email they are routable, shareable and transcribed like voice items; from anyone else they wait for the owner's Approve or Decline.
191 changes: 191 additions & 0 deletions dashboard/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -39289,6 +39289,197 @@
}
}
},
"/api/inbox/email": {
"post": {
"tags": [
"Inbox"
],
"summary": "Receive mail-in files (hub relay)",
"description": "Markdown, audio and image attachments hive-mx received for hive@<host>. A sender whose From address passed DMARC alignment and is a proven calendar email of a user with access becomes normal Inbox items; anyone else's items await the owner's approval. Relay signature: X-Hive-Relay-Timestamp, X-Hive-Relay-Signature-256 (HMAC-SHA256 with this hive's relay key over timestamp.delivery.body) and X-Hive-Relay-Delivery; no session.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "hive-mx delivery (pkg/mailin/wire.Delivery) of kind files: id, kind, recipient, message_id, received_at, auth, files {title, attachments[] {name, kind, content_type, size, sha256, data}}"
}
}
}
},
"responses": {
"200": {
"description": "Stored",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "string"
}
},
"awaiting_approval": {
"type": "boolean"
}
}
}
}
}
},
"400": {
"description": "Invalid delivery"
},
"401": {
"description": "Relay signature rejected"
},
"409": {
"description": "Mail-in files are off or unavailable"
},
"413": {
"description": "Delivery too large"
},
"503": {
"description": "This hive holds no relay key"
},
"507": {
"description": "The email spool is full"
}
}
}
},
"/api/inbox/email/{id}/approve": {
"post": {
"tags": [
"Inbox"
],
"summary": "Approve a mailed-in item",
"description": "Lets an item from outside the allowlist be shared, routed and transcribed. Owner only. Audited as inbox-email-approve.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Email item id"
}
],
"responses": {
"200": {
"description": "The item",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Inbox item"
}
}
}
},
"403": {
"description": "Owner access required"
},
"404": {
"description": "No such email item"
},
"503": {
"description": "Mail-in files are not available"
}
}
}
},
"/api/inbox/email/{id}/decline": {
"post": {
"tags": [
"Inbox"
],
"summary": "Decline a mailed-in item",
"description": "Deletes the item and its file. Owner only. Audited as inbox-email-decline.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Email item id"
}
],
"responses": {
"200": {
"description": "Deleted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"declined": {
"type": "boolean"
}
}
}
}
}
},
"403": {
"description": "Owner access required"
},
"404": {
"description": "No such email item"
},
"503": {
"description": "Mail-in files are not available"
}
}
}
},
"/api/inbox/email/{id}/file": {
"get": {
"tags": [
"Inbox"
],
"summary": "Download a mailed-in file",
"description": "The stored attachment with its sniffed type (Markdown as text/plain), inline for images and as a download otherwise, X-Content-Type-Options nosniff and a sandbox Content-Security-Policy. Owner or read-write.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Email item id"
}
],
"responses": {
"200": {
"description": "The file",
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"403": {
"description": "Owner or read-write access required"
},
"404": {
"description": "No such email item"
},
"503": {
"description": "Mail-in files are not available"
}
}
}
},
"/api/inbox/route": {
"post": {
"tags": [
Expand Down
3 changes: 3 additions & 0 deletions src/cmd/hive/boot_inbox.go
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,9 @@ func (b *boot) bootInbox(baseDir string) {
Fetcher: &inbox.LinkFetcher{UserAgent: "hive-inbox/" + version},
}
svc.EnableUploads(uploads)
// Files mailed to hive@<host> through hive-mx (#18395) are spooled on
// this spoke's data volume (0700 dirs, 0600 files).
svc.EnableEmail(&inbox.EmailSource{Dir: filepath.Join(baseDir, "connector-state", "email", "items")})
b.startInboxUploadRetention(uploads)
// Dashboard recordings (● Record): audio under connector-state/recordings
// until inbox.recording.retention_days, facts in the personal layer.
Expand Down
4 changes: 4 additions & 0 deletions src/docs/api-reference/knowledge.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,10 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `POST` | `/api/knowledge/connectors/{name}/auth/complete` | Owner only | Finish a sign-in from pasted material on a hosted hive: `{redirect_url}` (Plaud: the `localhost:8199/auth/callback?…` URL the browser landed on, forwarded in-pod while the login is pending; Zoom, Google Meet and Webex: the registered redirect URL with `code` and `state`, exchanged for tokens kept in the connector token store) or `{tokens}` (Plaud only: contents of `~/.plaud/tokens-mcp.json`); see [inbox-voice-sources.md](../inbox-voice-sources.md) | `pkg/dashboard/api_inbox.go:32` |
| `GET` | `/api/inbox` | Dashboard auth/session | Inbox items (voice recordings, dictations and meeting recordings keyed by `(source, id)`) with per-destination route state, source connection status, candidate repos and auto-routing settings; see [inbox-voice-sources.md](../inbox-voice-sources.md) | `pkg/dashboard/api_inbox.go:24` |
| `POST` | `/api/inbox/route` | Owner only | Route one item: `{source, item_id, destination: spek_rfc\|dibs\|dismiss, repo?}` (202 queued; 400 unconfigured destination, 404 unknown item, 409 already queued/running) | `pkg/dashboard/api_inbox.go:25` |
| `POST` | `/api/inbox/email` | Hub relay signature | Mail-in files hive-mx received for `hive@<host>` ([#18395](https://github.com/hivecommons/hive/issues/18395)): Markdown, audio and image attachments become `email` Inbox items under `connector-state/email/items`. A sender who passed DMARC alignment and is a proven calendar email of a user with access gets normal items; anyone else's items carry `awaiting_approval` and cannot be shared, routed or transcribed until approved. `200 {items, awaiting_approval}`; `409` off (`meetings.email.files_enabled`); `507` spool full (256 MiB); `401` bad relay signature | `pkg/dashboard/api_inbox_email.go:21` |
| `POST` | `/api/inbox/email/{id}/approve` | Owner only | Approve a mailed-in item from outside the allowlist. Audited as `inbox-email-approve` | `pkg/dashboard/api_inbox_email.go:22` |
| `POST` | `/api/inbox/email/{id}/decline` | Owner only | Delete a mailed-in item and its file. Unapproved items are also deleted after 14 days. Audited as `inbox-email-decline` | `pkg/dashboard/api_inbox_email.go:23` |
| `GET` | `/api/inbox/email/{id}/file` | Owner or read-write | The stored file with its sniffed type (Markdown as `text/plain`), inline for images, `nosniff` and a sandbox CSP | `pkg/dashboard/api_inbox_email.go:24` |
| `POST` | `/api/inbox/dismiss` | Owner only | Bulk "Knowledge only": `{items: [{source, item_id}], undo?}` | `pkg/dashboard/api_inbox.go:26` |
| `GET` | `/api/inbox/settings` | Dashboard auth/session | Auto-routing rules, default RFC repo, dibs URL, destination readiness | `pkg/dashboard/api_inbox.go:27` |
| `POST` | `/api/inbox/settings` | Owner only | Update `inbox.rules` / `inbox.spek.repo` / `inbox.dibs.url` in the runtime config (omitted fields unchanged) | `pkg/dashboard/api_inbox.go:28` |
Expand Down
35 changes: 35 additions & 0 deletions src/docs/inbox-voice-sources.md
Original file line number Diff line number Diff line change
Expand Up @@ -419,6 +419,41 @@ for a conversation Otter has no transcript for
([inbox-transcription.md](inbox-transcription.md)). Setup is in
[knowledge-connectors.md](knowledge-connectors.md#otterai-conversations-type-otter).

## Files mailed to hive@ (email)

Mail sent to `hive@<your hive's dashboard host>` with Markdown (`.md`),
audio (`.m4a`, `.mp3`, `.wav`, `.ogg`, `.webm`) or image (`.png`, `.jpg`,
`.gif`, `.webp`) attachments reaches the cluster's receive-only mail
receiver, hive-mx, which keeps only those attachments (type checked by
content, at most 10 files and 2 MB per message) and the subject, and the hub
relays them to the hive ([#18395](https://github.com/hivecommons/hive/issues/18395);
how mail reaches hive-mx is in [meetings.md](meetings.md#inviting-betty-by-email)).
Each attachment becomes one `email` item (✉️), titled with the subject (and
the file name when a mail carries several), spooled on the spoke's data
volume under `connector-state/email/items` (0700 directories, 0600 files,
256 MiB in all).

- **Who lands directly:** a sender whose `From` address passed DMARC
alignment and is a proven calendar email of a user with owner, read-write
or read access (see
[Proving calendar emails](meetings.md#proving-calendar-emails)). Their
items are like any other Inbox item: routable to spek or dibs, shareable,
matched by auto-routing rules (`source: email`).
- **Everyone else** waits: the item shows **awaiting approval** with
**✓ Approve** and **✕ Decline** for the owner. Until approved it cannot be
shared, routed or transcribed, and rules skip it; approving lets the rules
apply on the next sweep. Declining deletes it; unapproved items are
deleted after 14 days.
- **Markdown** is the item's text, marked as untrusted data written by the
sender. **Audio** goes through the same transcription path as voice items
([inbox-transcription.md](inbox-transcription.md)), read from the spool
instead of a download link; auto transcription applies when
`inbox.transcription.sources` includes `email`. **Images** are stored
as attachments of the item and shown as a thumbnail; **📎 Open file**
downloads any of them (owner and read-write).
- Nothing in a mail is executed or followed. Turn mail-in files off with
`meetings.email.files_enabled: false`; senders then get a bounce.

## Configuration

```yaml
Expand Down
1 change: 1 addition & 0 deletions src/pkg/dashboard/api_inbox.go
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ func (s *Server) registerInboxRoutes() {
s.mux.HandleFunc("GET /api/inbox/transcriptions", s.handleInboxTranscriptions)
s.registerInboxUploadRoutes()
s.registerInboxSpekRunner()
s.registerInboxEmailRoutes()
}

// inboxSourceReadTimeout bounds one read that may spawn the source's MCP
Expand Down
Loading
Loading