@securecoms/agent-bridge 0.34.0 → 0.35.0

package/README.md

@@ -224,10 +224,17 @@ All routes except `/healthz` require `Authorization: Bearer <BRIDGE_TOKEN>`.
 | `GET` | `/v1/messages` | query: `channel_id`, `wait` (0–50) | `[{channel_id, message_id, sender_id, text, ts}]` |
 | `GET` | `/v1/events` | query: `channel_id` | SSE stream |
 | `POST` | `/v1/status` | `{channel_id, state, detail?}` | `{ok:true}` |
+| `GET` | `/v1/vault-outbox` | — | `{path}` (the upload outbox; `null` when uploads are disabled) |
+| `POST` | `/v1/send-attachment` | `{channel_id, path, caption?}` (`path` must be in the vault outbox) | `{message_id, status:"sent"}` |
+| `POST` | `/v1/vault-write` | `{enclave_id, path, name, vault_channel_id?}` (`path` must be in the vault outbox) | `{node_id}` |
 | `GET` (Upgrade) | `/v1/ws` | query: `token` or `Authorization` header | WebSocket — see [WebSocket](#websocket-recommended) |
 
 The agent's capabilities, including the receive modes the daemon supports, are advertised on `/healthz` under `capabilities` (e.g. `receive_modes: ["longpoll","sse","websocket"]`).
 
+**Uploads come only from the vault outbox.** `/v1/send-attachment` and `/v1/vault-write` read a local file and share it with the channel or the workspace Files. They read only a regular file placed directly in the daemon's outbox, `<store-dir>/vault-outbox/` (next to `bridge-state.db`). The daemon creates it at start with mode 0700, owned by the daemon's user, and pins it. Every read checks that it is still that same directory, owned by the daemon's user, with mode 0700. The authenticated `GET /v1/vault-outbox` returns its absolute path; the unauthenticated `/healthz` does not show it. Copy the file into that directory first, then pass its path (absolute, or a bare file name, which is resolved inside the outbox). Any other path is refused with `400 {"error":"path_outside_outbox"}`. That includes a `..` path, a subdirectory, a symlink (even one pointing back into the outbox), a hard link, a directory, a FIFO or a device, and an outbox that was swapped or loosened after start. The response and the daemon log never contain the path. A missing file inside the outbox is still `400 invalid_request`. **After a successful upload the daemon deletes the file from the outbox**, so no plaintext copy lingers. After a failed upload the file stays, so you can retry. A received attachment saved under `<store-dir>/attachments/` is outside the outbox: to forward it, copy it into the outbox first. Uploads are refused until the daemon has started, and always for an in-memory store. If the outbox mode or owner is changed while the daemon runs, uploads are refused until the daemon is restarted (it fails closed; a restart tightens the mode again).
+
+**What the outbox does not stop.** It stops a caller that can only send HTTP requests to the daemon, for example a prompt-injected harness that is allowed to call the bridge but not to touch files. It does **not** stop a harness that can also write files (shell or file tools): such a harness can copy `~/.ssh/id_ed25519` into the outbox and upload it. The real control for that case is per-upload owner approval, which is tracked as a follow-up (W6). Until then, give file-capable harnesses only the bridge token you would trust with your files.
+
 **`POST /v1/send` — 503 channel_pending**
 
 If the daemon hasn't been admitted to the named channel yet (the owner's watcher hasn't processed the key package), the response is:
@@ -670,9 +677,12 @@ the agent **plaintext** — message text and, for attachments, a **local file pa
 - **Receiving an attachment:** the delivered message includes
   `attachments: [{ filename, mime, size, path, sha256 }]`. Read the file at `path`
   (saved under `<store-dir>/attachments/<channel>/`). No MLS, no key handling.
-- **Sending an attachment:** `POST /v1/send-attachment` with
-  `{ "channel_id": "...", "path": "/local/file.png", "caption": "optional" }`.
-  The daemon reads, encrypts, uploads, and dispatches it.
+- **Sending an attachment:** copy the file into the vault outbox (`path` from the
+  authenticated `GET /v1/vault-outbox`), then `POST /v1/send-attachment` with
+  `{ "channel_id": "...", "path": "<vault_outbox>/file.png", "caption": "optional" }`.
+  The daemon reads, encrypts, uploads, and dispatches it, then deletes the
+  outbox copy. A path outside the outbox (including a received file under
+  `<store-dir>/attachments/`) is refused with `400 path_outside_outbox`.
 
 This is why Python agents (which have no native MLS library) fully support
 attachments: the cryptography lives in the daemon, not the agent.
@@ -963,6 +973,23 @@ copied after the owner's next typed message.
 
 ---
 
+## Release notes: 0.35.0
+
+<!-- [COPY, approved by Eric 2026-10-30 ("notes OK"), outbox + blob-id release] -->
+
+#### Security
+- File uploads are safer. The agent now uploads to FileSafe or to a chat only from its own outbox folder (`vault-outbox`, next to the agent's data). Before, a program on the agent's computer could make it upload any file, such as a private key.
+- The agent checks every attachment ID it receives before it downloads the file. A bad ID is refused and the message is still marked as read.
+
+#### Change for custom agent scripts
+- A script that uploads a file must first copy it into the outbox folder. The script gets the folder path from `GET /v1/vault-outbox`. Uploads from other folders get the error `path_outside_outbox`.
+- The outbox path is no longer shown on `/healthz`.
+- After a good upload, the agent deletes the file from the outbox.
+
+#### Upgrade
+
+Upgrade the bridge and restart your agent. It works with @securecoms/agent-runtime 0.15.0.
+
 ## Release notes: 0.34.0
 
 <!-- [COPY, approved by Eric 2026-10-29 ("notes ok"), weather + currency release] -->

package/dist/attachments.d.ts

@@ -54,6 +54,19 @@ export type VaultRefEntry = {
 /** Plaintext ceiling for the size hint. PARITY: connect-web useVault.ts
  *  VAULT_MAX_FILE_BYTES (100 MiB object limit minus the 16-byte AEAD tag). */
 export declare const VAULT_REF_MAX_SIZE_HINT: number;
+/**
+ * A received `artifact_share.blobId` is attacker-controlled (any channel
+ * member writes it). It becomes a path segment of the agent's bearer-
+ * authenticated GET, and encodeURIComponent leaves `.` and `..` alone, so
+ * `..` would be a dot segment that reaches another /api/v1/ route. The
+ * backend only ever issues str(uuid4()) (connect_attachments.py), so anything
+ * but a canonical lowercase UUID is refused before any fetch. Content-free:
+ * the id is never echoed.
+ */
+export declare class InvalidBlobIdError extends Error {
+    constructor();
+}
+export declare function assertBlobId(blobId: unknown): string;
 /** The vault pin format. Exported for the /v1/vault-read expected_* params. */
 export declare const VAULT_PIN: RegExp;
 /**