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-inbox-upload-links.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Add links to the Inbox: paste a URL onto the Inbox or type it into + Add, and the hive fetches it once and reads it like a dropped file (a web page becomes readable markdown titled by its `<title>`; a linked JSON, CSV or Markdown file becomes that kind; `.html` files can be dropped too). The fetch is SSRF-guarded: http/https only, no credentials in the URL, the hive's own DNS lookup with the connection pinned to the checked address (private, loopback, link-local, CGNAT, multicast, IPv6 ULA and cloud metadata addresses refused), every redirect re-checked (at most 3), size and time caps, and `User-Agent: hive-inbox/<version>`; see `docs/inbox-uploads.md`.
140 changes: 133 additions & 7 deletions dashboard/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -38693,7 +38693,8 @@
"jsonl",
"yaml",
"csv",
"tsv"
"tsv",
"html"
]
},
"code": {
Expand Down Expand Up @@ -38758,7 +38759,8 @@
"jsonl",
"yaml",
"csv",
"tsv"
"tsv",
"html"
]
},
"code": {
Expand Down Expand Up @@ -38823,7 +38825,8 @@
"jsonl",
"yaml",
"csv",
"tsv"
"tsv",
"html"
]
},
"code": {
Expand Down Expand Up @@ -38894,7 +38897,8 @@
"jsonl",
"yaml",
"csv",
"tsv"
"tsv",
"html"
]
},
"code": {
Expand Down Expand Up @@ -38959,7 +38963,8 @@
"jsonl",
"yaml",
"csv",
"tsv"
"tsv",
"html"
]
},
"code": {
Expand Down Expand Up @@ -39024,7 +39029,8 @@
"jsonl",
"yaml",
"csv",
"tsv"
"tsv",
"html"
]
},
"code": {
Expand Down Expand Up @@ -39089,7 +39095,8 @@
"jsonl",
"yaml",
"csv",
"tsv"
"tsv",
"html"
]
},
"code": {
Expand Down Expand Up @@ -39792,6 +39799,125 @@
}
}
},
"/api/inbox/uploads/url": {
"post": {
"tags": [
"Knowledge"
],
"summary": "Add a link to the Inbox",
"description": "Owner or read-write. The hive fetches the URL itself under an SSRF guard: http/https only, no user name or password, its own DNS lookup with the connection pinned to the checked address (any private, loopback, link-local, CGNAT, multicast, IPv6 ULA or cloud metadata answer refuses the link), every redirect re-checked (at most 3), the body capped at `inbox.uploads.max_file_bytes` and the whole fetch at 60 s; `HTTP(S)_PROXY` is not used, a matching `network.upstream_proxy` is asked to CONNECT to the checked IP. The body goes through the same type pipeline as an uploaded file (an HTML page becomes readable markdown titled by its `<title>`). Audited as `inbox_upload` with `origin=link` and the host.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string"
}
}
}
}
}
},
"responses": {
"201": {
"description": "One file added",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"filename": {
"type": "string"
},
"ok": {
"type": "boolean"
},
"source": {
"type": "string",
"enum": [
"upload"
]
},
"item_id": {
"type": "string"
},
"title": {
"type": "string"
},
"kind": {
"type": "string",
"enum": [
"markdown",
"text",
"json",
"jsonl",
"yaml",
"csv",
"tsv",
"html"
]
},
"code": {
"type": "string",
"enum": [
"empty",
"too_large",
"unsupported_type",
"parse_failed",
"quota_exceeded",
"too_many_files",
"internal"
]
},
"error": {
"type": "string"
}
}
}
}
}
}
}
}
},
"400": {
"description": "No url, or the link breaks the fetch rules (`link_refused`)"
},
"403": {
"description": "Not owner or read-write, or a cross-site request"
},
"404": {
"description": "The hive has no upload store"
},
"413": {
"description": "The linked file is too large"
},
"415": {
"description": "Unsupported type"
},
"422": {
"description": "The linked file does not parse"
},
"502": {
"description": "The site could not be reached or answered an error (`fetch_failed`)"
},
"507": {
"description": "The per-hive upload quota is full"
}
}
}
},
"/api/inbox/transcriptions": {
"get": {
"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 @@ -57,6 +57,9 @@ func (b *boot) bootInbox(baseDir string) {
ConnectorsDir: filepath.Join(baseDir, "connectors"),
FactWritten: b.inboxUploadFactWritten,
Logger: b.logger,
// Links are fetched by the hive with the SSRF guard (own DNS
// lookup, blocked ranges, every redirect re-checked).
Fetcher: &inbox.LinkFetcher{UserAgent: "hive-inbox/" + version},
}
svc.EnableUploads(uploads)
b.startInboxUploadRetention(uploads)
Expand Down
3 changes: 2 additions & 1 deletion src/docs/api-reference/knowledge.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,8 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `GET` | `/api/inbox/transcriptions` | Dashboard auth | Live progress of queued and running transcriptions in queue order (`{active: [{source, id, state}]}` with `phase`, `progress`, `estimated`, `started_at`, `audio_seconds`, `processed_seconds`, `eta_seconds`, `queue_position`); reads no source, so the Inbox polls it every 3 s while a job runs; `Cache-Control: no-store`; see [inbox-transcription.md](../inbox-transcription.md) | `pkg/dashboard/api_inbox.go:34` |
| `GET` | `/api/inbox/{source}/{id}/audio` | Owner or read-write | Mint a fresh short-lived audio/video link for one item (`{url, expires_at}`; Plaud: presigned, 24h; Zoom: audio-only or video `download_url` with a one-hour download token; Webex: the recording's temporary direct audio (else MP4) download link, valid 3 hours; Teams and Google Meet: 404, no browser-playable link; Slack huddles: 404, Slack keeps no huddle audio; Otter: the conversation's MP3 download link (`GET /conversations/{id}/audio`), minted per click; Granola: 404, Granola keeps no meeting audio; Limitless: 404, Pendant audio is served only behind the API key; Fathom: the signed url of a recording download (`POST /recordings/{id}/download`, audio-only recordings complete at once, video is polled), valid about 24 hours; Fireflies: the transcript's hashed `audio_url` (else `video_url`), valid 24 hours, Pro plan or higher); never stored by the hive, replied with `Cache-Control: no-store`, audited as `inbox_audio` (403 role, 404 unknown item or no audio, 502 source unreachable) | `pkg/dashboard/api_inbox.go:30` |
| `GET` | `/api/inbox/{source}/{id}/audio/stream` | Owner or read-write | Stream one item's audio from the dashboard origin, for the Inbox player (the CSP refuses cross-origin media). The hive mints the link as above, fetches it server-side and copies the bytes with the media `Content-Type` (from storage, else the link's extension); a single `Range: bytes=…` is passed through (206 + `Content-Range`; 200 whole file when storage ignores it; 416 passed through). The link stays in memory for one playback's Range requests (10 min, never past expiry), is never logged, returned or stored, and is re-minted once when storage refuses it; nothing is written to disk. `Cache-Control: no-store`; audited as `inbox_audio_stream` once per minted link (403 role, 404 unknown item or no audio, 413 over the 2 GiB cap, 502 source or storage unreachable, or link refused/expired) | `pkg/dashboard/api_inbox.go:31` |
| `POST` | `/api/inbox/uploads` | Owner or read-write | Add dropped files to the Inbox: `multipart/form-data` with one or more `file` fields (at most `inbox.uploads.max_files_per_drop`, default 20, each up to `inbox.uploads.max_file_bytes`, default 25 MiB). Each file is typed by content (magic bytes, UTF-8, a parse check), never by name or client MIME alone; md, txt, json, jsonl, yaml, csv and tsv become `upload` items with extracted markdown and a Knowledge fact. One file: 201 `{results: [{filename, ok, source, item_id, title, kind}]}` or its refusal (400 `empty`/`too_many_files`, 413 `too_large`, 415 `unsupported_type`, 422 `parse_failed`, 507 `quota_exceeded`, each with `code` and `error`); several files: 200 with per-file results unless all failed. Cross-site requests are refused; every file is audited as `inbox_upload` (403 role, 404 no upload store); see [inbox-uploads.md](../inbox-uploads.md) | `pkg/dashboard/api_inbox_uploads.go:26` |
| `POST` | `/api/inbox/uploads` | Owner or read-write | Add dropped files to the Inbox: `multipart/form-data` with one or more `file` fields (at most `inbox.uploads.max_files_per_drop`, default 20, each up to `inbox.uploads.max_file_bytes`, default 25 MiB). Each file is typed by content (magic bytes, UTF-8, a parse check), never by name or client MIME alone; md, txt, json, jsonl, yaml, csv, tsv and html become `upload` items with extracted markdown and a Knowledge fact. One file: 201 `{results: [{filename, ok, source, item_id, title, kind}]}` or its refusal (400 `empty`/`too_many_files`, 413 `too_large`, 415 `unsupported_type`, 422 `parse_failed`, 507 `quota_exceeded`, each with `code` and `error`); several files: 200 with per-file results unless all failed. Cross-site requests are refused; every file is audited as `inbox_upload` (403 role, 404 no upload store); see [inbox-uploads.md](../inbox-uploads.md) | `pkg/dashboard/api_inbox_uploads.go:27` |
| `POST` | `/api/inbox/uploads/url` | Owner or read-write | Add a link: `{url}`. The hive fetches it under the SSRF guard (http/https only, no credentials, its own DNS lookup with the connection pinned to the checked address, private/loopback/link-local/CGNAT/multicast/ULA/metadata ranges refused, every redirect re-checked, at most 3, body capped at `inbox.uploads.max_file_bytes`, 60 s) and runs the body through the upload type pipeline (an HTML page becomes readable markdown titled by its `<title>`). 201 `{results: [{filename: host, ok, source, item_id, title, kind}]}`; 400 `link_refused`, 413, 415, 422, 502 `fetch_failed`, 507; audited as `inbox_upload` with `origin=link` and the host (403 role, 404 no upload store) | `pkg/dashboard/api_inbox_uploads.go:28` |
| `POST` | `/api/inbox/recordings` | Owner or read-write | Start a dashboard recording (● Record): `{title, mime: audio/webm\|audio/mp4, consent_version, includes_tab_audio}`. `consent_version` must name the current consent notice; it is stored with the user in the recording's metadata. One recording per user at a time. 201 `{id, max_chunk_bytes, max_seconds, retention_days, transcribes}`; audited as `inbox_recording_start` (400 consent missing or stale, 403 role, 409 `{active_id}` already recording, 412 `inbox.recording.enabled` off, 415 other media types, 507 `inbox.recording.quota_bytes` used up); see [inbox-recording.md](../inbox-recording.md) | `pkg/dashboard/api_inbox_recordings.go:20` |
| `POST` | `/api/inbox/recordings/{id}/chunks` | The recorder (owner or read-write) | Store one MediaRecorder chunk `?seq=N`, the raw bytes as the body (at most `max_chunk_bytes`, 512 KiB). In order only; each part is fsynced before the 200 `{id, seq, next_seq, bytes, duplicate?}`. The first chunk must start with a WebM or MP4 signature; the hive never decodes audio. A re-send with the same bytes is acknowledged again (`duplicate: true`) (400 bad seq, 403 someone else's, 409 `{expected_seq}` gap, other bytes for a stored seq, or already ended, 413 chunk over 512 KiB or past `max_bytes` / `max_seconds`, 415 not WebM/MP4, 507 quota) | `pkg/dashboard/api_inbox_recordings.go:21` |
| `POST` | `/api/inbox/recordings/{id}/finalize` | The recorder | End a recording: `{duration_ms?}` (the recorder's count, pauses excluded). The chunks are concatenated in order into `audio.webm` or `audio.mp4`, a pending Knowledge fact (personal layer) is written and the item appears in the Inbox. 200 `{id, state, title, duration_ms, bytes, chunks, transcribes}`; audited as `inbox_recording_finalize` (400 no chunk received, 403, 404, 409 already ended) | `pkg/dashboard/api_inbox_recordings.go:22` |
Expand Down
48 changes: 45 additions & 3 deletions src/docs/inbox-uploads.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,9 @@

Besides the recordings that [voice and meeting connectors](inbox-voice-sources.md)
bring in, the owner can add material to the Inbox directly: drop a file onto
the Inbox, choose it with **+ Add**, or paste it with Ctrl/Cmd+V while the
Inbox has focus. Each file becomes an Inbox item like any other: it gets a
the Inbox, choose it with **+ Add**, paste it with Ctrl/Cmd+V while the
Inbox has focus, or add a link (type it into + Add, or paste a URL onto the
Inbox). Each file becomes an Inbox item like any other: it gets a
Knowledge fact, the 🔗 Share ▾ menu (RFC, Knowledge, DIBS) and the route
history.

Expand All @@ -28,6 +29,7 @@ as plain text otherwise.
| JSON Lines | `.jsonl`, `.ndjson` | the record count and the first 20 records in a fenced block; every line is validated |
| YAML | `.yaml`, `.yml` | a one-line summary and the document in a fenced `yaml` block (parsed with `gopkg.in/yaml.v3`) |
| CSV / TSV | `.csv`, `.tsv`, `.tab` | row and column counts and a markdown table of the first 20 rows (20 columns at most) |
| HTML | `.html`, `.htm`, and web pages behind a link | readable markdown: the `<title>` names the item; the `<article>` or `<main>` (else `<body>`) is kept with headings, paragraphs, lists, quotes, code, tables, link targets and image alt text; scripts, styles, forms, navigation, footers, asides and hidden elements are dropped. Parsed with `golang.org/x/net/html` (BSD-3-Clause); nothing is executed and nothing the page references is loaded |

Text is validated as UTF-8 (a UTF-8 BOM is dropped; UTF-16 is refused with
"save the file as UTF-8") and newlines are normalised to `\n`. The fenced
Expand Down Expand Up @@ -68,6 +70,41 @@ Every file, accepted or refused, is audited as `inbox_upload` with the user,
the item id, the detected kind, the size and the outcome or refusal code; the
file's content and name are not written to the audit log.

## Links

A link is fetched by the hive itself, once, when it is added, and its body
goes through the same type pipeline as a dropped file: an HTML page becomes
text, a link to a `.json`, `.csv` or `.md` file becomes that kind (the file
name in the URL or `Content-Disposition`, else the response `Content-Type`,
picks the format, and the content must still pass the sniff and the parse).
YouTube and other streaming pages are read as HTML pages, never as video;
links to audio or video files are refused for now.

The item is titled by the page `<title>`, else the file name, else the URL,
and shows **link · host**. The URL is kept as the item's provenance (and the
fact's `source_url`) only.

Fetch rules (SSRF protection):

- `http` and `https` only; a link with a user name or password is refused.
- The hive resolves the host itself and connects to the address it checked;
if **any** answer is blocked the link is refused, so a second
(rebinding) answer is never used. Blocked: loopback, RFC 1918 private,
link-local (including the cloud metadata address `169.254.169.254`),
CGNAT `100.64.0.0/10`, multicast, reserved and documentation ranges,
`0.0.0.0/8`, IPv6 unspecified, loopback, unique-local `fc00::/7`
(including `fd00:ec2::254`), link-local and site-local, Teredo, and IPv4
addresses embedded in IPv4-mapped, NAT64 and 6to4 addresses; host names
`localhost`, `*.localhost`, `*.local`, `*.internal` and `metadata`.
- Every redirect hop is checked the same way, at most 3 redirects, and a
redirect never carries `Authorization` or `Cookie`.
- The body is streamed through a limit (`inbox.uploads.max_file_bytes`);
connect 10 s, TLS 10 s, response headers 15 s, whole fetch 60 s.
- Requests send `User-Agent: hive-inbox/<version>`.
- `HTTP(S)_PROXY` from the environment is not used (a proxy would resolve
the name again). When `network.upstream_proxy` matches the host, the hive
asks the proxy to `CONNECT` to the checked IP and port.

## Limits

All limits have defaults; `inbox.uploads` in `hive.yaml` overrides them and
Expand Down Expand Up @@ -111,6 +148,11 @@ and its share history stay. Text documents are kept unless

## API

`POST /api/inbox/uploads/url` (owner or read-write) takes `{"url": "..."}`
and answers like a single-file upload (201, or 400 `link_refused`, 413, 415,
422, 502 `fetch_failed`, 507); refusals and additions are audited as
`inbox_upload` with `origin=link` and the host, never the full URL.

`POST /api/inbox/uploads` (owner or read-write) takes `multipart/form-data`
with one or more `file` fields. One file answers `201` with
`{results: [{filename, ok: true, source: "upload", item_id, title, kind}]}`,
Expand All @@ -123,4 +165,4 @@ files answer `200` with one result per file unless all of them failed. See
`GET /api/inbox` reports the limits and current usage under
`settings.uploads` (`enabled`, `max_file_bytes`, `max_files_per_drop`,
`quota_bytes`, `used_bytes`, `media_retention_days`,
`document_retention_days`, `extensions`).
`document_retention_days`, `extensions`, `links`).
Loading
Loading