@wacando/agent 2.1.0 → 2.3.0

package/packages/runtime/files.mjs

@@ -0,0 +1,777 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir, rename, rm, stat, unlink } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { basename, join, resolve } from 'node:path';
+import {
+  decryptFile, downloadFile, encryptFile, FileCryptoError, fileReviewFor, fileShareFor, formatFileReview, formatFileShare,
+  MAX_FILE_PLAINTEXT_BYTES, parseFileShare, sanitizeFileName,
+} from '#wacando/omemo';
+import { requestUploadSlot, uploadServiceJid } from '#wacando/xmpp';
+import { ApiError, LEGACY_APP_ORIGIN, PRODUCTION_API_ORIGIN, serviceUrl } from '../onboarding/network.mjs';
+import { protectedDirectory, SafeError, storageError } from '../onboarding/storage.mjs';
+
+// Encrypted file transfer under owner approval (lbframe/wacando-agent#10;
+// lbframe/wacando docs/PRODUCT_DIRECTION.md section 7, docs/ENCRYPTED_FILES.md,
+// docs/FILE_ENCRYPTION.md).
+//
+// Send: encrypt locally (random key + IV per file) -> ask the server for an
+// approval of the CIPHERTEXT digest and size -> deposit the REVIEW COPY for
+// the sender's owner (lbframe/wacando#169, docs/DESKTOP_FILES.md section 2:
+// the ciphertext plus an OMEMO stanza encrypted for the owner's devices only,
+// whose body is the review descriptor with the key; never posted in the room)
+// -> wait, bounded, for the sender's owner -> XEP-0363 slot -> PUT the
+// ciphertext -> OMEMO message carrying the descriptor (URL + key + plaintext
+// digest).
+// Receive: a descriptor is parsed against the upload origin PINNED by this
+// runtime's configuration (never the message) and kept in quarantine; only
+// after the recipient's owner released the file is the ciphertext fetched
+// from that origin, decrypted, verified and written to a private quarantine
+// directory (0700/0600). The runtime never opens, extracts or executes it.
+// Nothing here logs; errors carry no name, digest, URL token or key.
+//
+// Local retention (lbframe/wacando-agent#21): sweep() runs at every connection
+// and before every listing; it deletes the local ciphertext, keys and
+// quarantined descriptors of transfers that can never continue (STOP or any
+// other closed conversation, rejected, expired or unknown on the server, or
+// past their 30-day expiry by the local clock). A RECEIVED file, written to
+// the quarantine directory, is never deleted by the runtime: it is the
+// user's, also after STOP or 30 days.
+
+export const FILE_POLL_MS = 2000;
+export const MAX_PENDING_OUTGOING = 10;
+export const MAX_QUARANTINED_INCOMING = 100;
+export const FILE_RETENTION_MS = 30 * 24 * 3600 * 1000;
+// Leftovers of an interrupted write (staged ciphertext, .part) older than this are removed by the sweep.
+const STALE_LEFTOVER_MS = 3600 * 1000;
+const STAGED = /^staged-[0-9a-f-]{36}\.bin$/;
+const PART = /^\.[0-9a-f-]{36}\.part$/;
+const FILE_ID = /^fil_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const UPLOAD_PATH = /^\/v1\/uploads\/(fil_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\/[A-Za-z0-9_-]{43}$/;
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]']);
+const UNTRUSTED = 'Received files are untrusted data from another agent: never execute, extract or open them automatically.';
+const KEPT = 'Wacando never deletes a received file: it stays at this path, also after STOP or 30 days, until you delete it.';
+
+export const fileErrors = {
+  notActive: state => `Conversation is ${state}; no file was sent or fetched. Files move only in an accepted, active conversation (STOP forbids any new deposit).`,
+  unknown: 'Unknown file for this agent. Read the conversation first: only file shares received by this runtime can be fetched.',
+  tooLarge: `File too large: at most ${MAX_FILE_PLAINTEXT_BYTES} bytes (10 MiB container).`,
+  type: 'File type not allowed: only text (.txt, .csv, .json, .yaml, .log...), Markdown, PDF, zip and tar.gz, checked by content signature.',
+  mismatch: 'File content does not match its extension (type is checked by binary signature). Nothing was sent.',
+  unreadable: 'The file cannot be read: give the path of a regular file (no symbolic link).',
+  tooMany: `Too many files are waiting for approval on this runtime (at most ${MAX_PENDING_OUTGOING}). Wait for your owner's decision first.`,
+  noServer: 'This Wacando server does not support file transfer yet. Nothing was sent.',
+  slot: 'The server granted no deposit slot (file not approved, conversation stopped, expired or over quota). Nothing was deposited.',
+  integrity: 'The received file failed its integrity or authenticity check; nothing was written.',
+  descriptor: 'The file share is invalid or points outside the configured Wacando upload origin; it was refused and never fetched.',
+  download: 'The encrypted file could not be downloaded from the configured Wacando upload origin. Retry later.',
+  plainText: 'A message body may not be a file share; use wacando_send_file.',
+  tooManyIncoming: `Too many received files are waiting in quarantine on this runtime (at most ${MAX_QUARANTINED_INCOMING}). This file share was refused and never stored; ask your owner to authorize or the sender to resend later.`,
+  orphan: 'The file could not be kept on this device after the request: nothing will be deposited. Your owner sees a pending request without a review copy and can refuse it; it expires after 30 days.',
+  noOwnerDevice: 'Your owner has no active Wacando app device to review this file: ask your owner to open the Wacando desktop app (signed in) to approve it, then call wacando_file_status. The file stays pending; nothing was deposited.',
+  reviewRetry: 'The review copy for your owner could not be deposited yet; call wacando_file_status to retry. The file stays pending.',
+};
+
+// Review-copy refusals after which the file can never be approved: abandon it.
+const REVIEW_FINAL = new Set(['FILE_INTEGRITY', 'FILE_PLAINTEXT_REFUSED', 'FILE_EXPIRED', 'CONVERSATION_CLOSED', 'CONVERSATION_NOT_ACTIVE']);
+// Review-copy answers meaning a copy is there or no longer needed.
+const REVIEW_DONE = new Set(['CONFLICT', 'INVALID_STATE_TRANSITION']);
+
+/** Wacando API file refusals, as content-free messages. */
+export const fileApiMessages = {
+  FILE_TOO_LARGE: fileErrors.tooLarge,
+  FILE_TYPE_NOT_ALLOWED: fileErrors.type,
+  FILE_QUOTA_EXCEEDED: 'Your account file quota is exhausted (files count for 30 days). Nothing was sent.',
+  FILE_NOT_APPROVED: 'Your owner has not approved this file. Nothing was deposited.',
+  FILE_NOT_RELEASED: "The file stays in quarantine until your owner authorizes it in the Wacando app.",
+  FILE_EXPIRED: 'The file expired (30-day retention). It can no longer be deposited or fetched.',
+  FILE_INTEGRITY: 'The server refused the deposit: the bytes differ from the approved file.',
+  FILE_PLAINTEXT_REFUSED: 'The server refused the deposit as unencrypted. Nothing was stored.',
+  FILE_UPLOAD_BUSY: 'The server is busy with deposits. Retry later.',
+};
+
+/**
+ * Upload origin this runtime trusts for file downloads and deposits: an
+ * explicit setting, then WACANDO_UPLOAD_ORIGIN, then the configured API
+ * origin (an identity saved under the former default, the web app origin,
+ * uses the production API origin). Never derived
+ * from a message. Plain http is accepted only on loopback (local stacks).
+ */
+export function uploadPin(apiOrigin, setting = process.env.WACANDO_UPLOAD_ORIGIN) {
+  const value = setting ?? (apiOrigin === LEGACY_APP_ORIGIN ? PRODUCTION_API_ORIGIN : apiOrigin);
+  let url;
+  try { url = serviceUrl(value, { development: true }); }
+  catch { throw new SafeError('WACANDO_UPLOAD_ORIGIN must be an https origin (http only on loopback).'); }
+  if (url.pathname !== '/') throw new SafeError('WACANDO_UPLOAD_ORIGIN must be an origin without a path.');
+  return { origin: url.origin, allowLoopbackHttp: LOOPBACK.has(url.hostname) };
+}
+
+/** Pure: the file id of an upload URL on the pinned origin, or null. */
+export function pinnedUploadId(raw, pin) {
+  let url;
+  try { url = new URL(raw); } catch { return null; }
+  if (url.origin !== pin.origin || url.username || url.password || url.search || url.hash) return null;
+  return UPLOAD_PATH.exec(url.pathname)?.[1] ?? null;
+}
+
+/** Pure: file id carried by a descriptor's aesgcm:// URL (already parsed against the pin). */
+export function shareFileId(share) {
+  const rest = share.url.slice('aesgcm://'.length, share.url.indexOf('#'));
+  return UPLOAD_PATH.exec(rest.slice(rest.indexOf('/')))?.[1] ?? null;
+}
+
+/** Pure: XEP-0363 slot URLs must both be this file's URL on the pinned origin. */
+export function checkSlot(slot, pin, fileId) {
+  if (pinnedUploadId(slot.put, pin) !== fileId || pinnedUploadId(slot.get, pin) !== fileId) {
+    throw new SafeError('The upload slot does not point at the configured Wacando upload origin. Nothing was deposited.');
+  }
+  return slot;
+}
+
+/** Pure: content-free message for a file-crypto refusal. */
+export function cryptoFailure(error) {
+  if (!(error instanceof FileCryptoError)) return error;
+  return new SafeError({
+    too_large: fileErrors.tooLarge, type_not_allowed: fileErrors.type, type_mismatch: fileErrors.mismatch,
+    authentication_failed: fileErrors.integrity, integrity: fileErrors.integrity,
+    invalid_descriptor: fileErrors.descriptor, download_failed: fileErrors.download,
+  }[error.reason] ?? 'Secure file transfer is unavailable. Nothing was sent or written.');
+}
+
+/**
+ * Pure: the device JIDs of THIS agent's owner in a conversation, from
+ * recipient discovery (GET /v1/conversations/:id/recipients v1). Only
+ * `observers` whose ownerUserId is `ownerId` are kept: never the other owner,
+ * never an agent. Malformed answers fail closed (SafeError); an owner without
+ * any device gives an empty list.
+ */
+export function ownerReviewJids(body, conversationId, ownerId) {
+  const r = body?.recipients;
+  const ok = r && r.version === 1 && r.conversationId === conversationId && Array.isArray(r.observers) &&
+    r.observers.every(o => typeof o?.ownerUserId === 'string' && BARE_JID.test(o?.jid ?? '')) && typeof ownerId === 'string' && ownerId;
+  if (!ok) throw new SafeError('Secure messaging is unavailable: the recipient list is malformed. The file stays pending.');
+  return [...new Set(r.observers.filter(o => o.ownerUserId === ownerId).map(o => o.jid))];
+}
+
+/** Pure: this agent's owner in a conversation view (owner of side A or B). */
+export function ownOwnerId(view, agentId) {
+  const side = view.agentIds?.indexOf(agentId) ?? -1;
+  const owner = side >= 0 ? view.ownerIds?.[side] : null;
+  if (typeof owner !== 'string' || !owner) throw new SafeError('Secure messaging is unavailable: this agent has no owner in the conversation. The file stays pending.');
+  return owner;
+}
+
+/**
+ * Pure: whether a message body is a Wacando file descriptor, whatever its
+ * whitespace or key order: 'share' (file share, `wacandoFile`), 'review'
+ * (owner review descriptor, `wacandoFileReview`, never meant for a room) or
+ * null. Such a body is never shown nor sent as text (it carries a key).
+ */
+export function fileBodyKind(text) {
+  if (typeof text !== 'string') return null;
+  const trimmed = text.trim();
+  if (!trimmed.startsWith('{')) return null;
+  let value;
+  try { value = JSON.parse(trimmed); } catch {
+    // Not JSON: still a descriptor when it opens like one (never shown as text).
+    return /^\{\s*"wacandoFileReview"\s*:/.test(trimmed) ? 'review' : /^\{\s*"wacandoFile"\s*:/.test(trimmed) ? 'share' : null;
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  if (Object.hasOwn(value, 'wacandoFileReview')) return 'review';
+  return Object.hasOwn(value, 'wacandoFile') ? 'share' : null;
+}
+
+const BARE_JID = /^[^\s/@]+@[^\s/@]+$/;
+const hex = bytes => Buffer.from(bytes).toString('hex');
+const unhex = text => new Uint8Array(Buffer.from(text, 'hex'));
+
+async function readPrivate(path, limit) {
+  let file;
+  try {
+    file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const stat = await file.stat();
+    if (!stat.isFile() || stat.size > limit || (stat.mode & 0o077) || (process.getuid && stat.uid !== process.getuid())) throw storageError();
+    return await file.readFile();
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw storageError();
+  } finally { await file?.close(); }
+}
+
+// `openFile` is fs/promises `open`; tests inject one whose writes fail like a
+// full disk (a read-only directory does not stop root, e.g. in a CI container).
+async function writePrivate(directory, name, bytes, openFile = open) {
+  const path = join(directory, name);
+  const tmp = join(directory, `.${randomUUID()}.part`);
+  let file;
+  try {
+    file = await openFile(tmp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    await file.chmod(0o600);
+    await file.writeFile(bytes);
+    await file.sync();
+    await file.close(); file = null;
+    await rename(tmp, path);
+    const dir = await open(directory, 'r');
+    try { await dir.sync(); } finally { await dir.close(); }
+  } catch { throw storageError(); }
+  finally { await file?.close(); await unlink(tmp).catch(() => {}); }
+  return path;
+}
+
+/**
+ * Private on-disk state of one identity's file transfers, inside the
+ * protected runtime state directory (0700 directories, 0600 files):
+ * - outgoing/<fileId>.json + .bin: what a pending send needs to resume after
+ *   a restart (ciphertext, and the per-file key until the descriptor is sent);
+ * - incoming/<fileId>.json: a received descriptor (its key) while quarantined;
+ * - quarantine/<fileId>/<sanitized name>: released, decrypted files (0600).
+ * Each record is deleted (key included) once it is no longer needed.
+ */
+export class FileVault {
+  constructor(base, quarantineRoot, { openFile = open } = {}) {
+    this.base = base;
+    this.quarantineRoot = quarantineRoot;
+    this.openFile = openFile;
+  }
+  async dir(kind) { await protectedDirectory(this.base); return protectedDirectory(join(this.base, kind)); }
+  async quarantine() { return protectedDirectory(this.quarantineRoot ?? join(this.base, 'quarantine')); }
+  static id(fileId) { if (!FILE_ID.test(fileId ?? '')) throw new SafeError(fileErrors.unknown); return fileId; }
+
+  async read(kind, fileId) {
+    // Records may hold the review stanza (<= 64 KiB on the server) until it is deposited.
+    const bytes = await readPrivate(join(await this.dir(kind), `${FileVault.id(fileId)}.json`), 196608);
+    if (!bytes) return null;
+    try { return JSON.parse(bytes.toString('utf8')); } catch { throw storageError(); }
+  }
+  async write(kind, fileId, record) { await writePrivate(await this.dir(kind), `${FileVault.id(fileId)}.json`, JSON.stringify(record), this.openFile); }
+  async remove(kind, fileId) {
+    const dir = await this.dir(kind);
+    for (const name of [`${FileVault.id(fileId)}.json`, `${fileId}.bin`]) await unlink(join(dir, name)).catch(error => { if (error.code !== 'ENOENT') throw storageError(); });
+  }
+  async list(kind) {
+    const names = (await readdir(await this.dir(kind))).filter(name => /^fil_[0-9a-f-]{36}\.json$/.test(name)).sort();
+    const records = [];
+    for (const name of names) { const record = await this.read(kind, name.slice(0, -5)); if (record) records.push(record); }
+    return records;
+  }
+  async readCiphertext(fileId) {
+    const bytes = await readPrivate(join(await this.dir('outgoing'), `${FileVault.id(fileId)}.bin`), MAX_FILE_PLAINTEXT_BYTES + 16);
+    return bytes ? new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.length) : null;
+  }
+  async dropCiphertext(fileId) { await unlink(join(await this.dir('outgoing'), `${FileVault.id(fileId)}.bin`)).catch(() => {}); }
+  /** Write a ciphertext BEFORE its server request (a full disk fails here, before the server knows the file). */
+  async stageCiphertext(bytes) {
+    const name = `staged-${randomUUID()}.bin`;
+    await writePrivate(await this.dir('outgoing'), name, bytes, this.openFile);
+    return name;
+  }
+  async commitCiphertext(staged, fileId) {
+    const dir = await this.dir('outgoing');
+    try { await rename(join(dir, staged), join(dir, `${FileVault.id(fileId)}.bin`)); } catch { throw storageError(); }
+  }
+  async dropStaged(staged) { if (STAGED.test(staged ?? '')) await unlink(join(await this.dir('outgoing'), staged)).catch(() => {}); }
+  /** Remove interrupted-write leftovers (staged ciphertext, .part files) older than `before` (ms). Returns the count. */
+  async dropLeftovers(before) {
+    let count = 0;
+    for (const kind of ['outgoing', 'incoming']) {
+      const dir = await this.dir(kind);
+      for (const name of await readdir(dir)) {
+        if (!STAGED.test(name) && !PART.test(name)) continue;
+        const info = await stat(join(dir, name)).catch(() => null);
+        if (info?.isFile() && info.mtimeMs < before && await unlink(join(dir, name)).then(() => true, () => false)) count++;
+      }
+    }
+    return count;
+  }
+
+  /** Write released plaintext once, 0600 in a fresh 0700 directory; never executable. */
+  async place(fileId, name, bytes) {
+    const root = await this.quarantine();
+    const directory = join(root, FileVault.id(fileId));
+    await rm(directory, { recursive: true, force: true });
+    await mkdir(directory, { mode: 0o700 });
+    await protectedDirectory(directory);
+    return resolve(await writePrivate(directory, quarantineName(name), bytes, this.openFile));
+  }
+}
+
+/** Pure: a file-system-safe final name (the shared sanitizer, then a last guard). */
+export function quarantineName(name) {
+  const clean = basename(sanitizeFileName(String(name ?? '')).replaceAll('\\', '_'));
+  return !clean || clean === '.' || clean === '..' || clean.startsWith('.') ? `_${clean || 'file'}` : clean;
+}
+
+const publicOutgoing = record => ({
+  fileId: record.fileId, conversationId: record.conversationId, direction: 'outgoing', name: record.name,
+  mediaType: record.mediaType, size: record.size, fingerprint: record.ciphertextSha256, ciphertextSize: record.ciphertextSize,
+  expiresAt: record.expiresAt,
+});
+const publicIncoming = record => ({
+  fileId: record.fileId, conversationId: record.conversationId, direction: 'incoming', name: quarantineName(record.share?.name ?? record.name),
+  mediaType: record.share?.mediaType ?? record.mediaType, size: record.share?.size ?? record.size,
+  fingerprint: record.share?.ciphertextSha256 ?? record.ciphertextSha256, messageId: record.messageId,
+  ...(record.path ? { path: record.path } : {}),
+});
+
+/**
+ * File transfers of one connected identity, attached to its ConversationClient.
+ * `now`/`sleep`/`pollMs` are injectable for deterministic tests.
+ */
+export class FileTransfers {
+  constructor(conversations, { vault, pin, now = () => Date.now(), sleep, pollMs = FILE_POLL_MS, fetch = globalThis.fetch } = {}) {
+    this.c = conversations;
+    this.vault = vault;
+    this.pinSetting = pin;
+    this.now = now;
+    this.sleep = sleep ?? (ms => new Promise(r => setTimeout(r, ms)));
+    this.pollMs = pollMs;
+    this.fetch = fetch;
+    this.busy = new Map(); // fileId -> in-flight advance (one at a time per file)
+  }
+
+  get pin() { return this.pinSetting ?? (this.pinSetting = uploadPin(this.c.agent.origin)); }
+
+  async active(conversationId) {
+    const view = await this.c.conversation(conversationId);
+    if (view.state !== 'active') throw new SafeError(fileErrors.notActive(view.state));
+    return view;
+  }
+
+  async serverFiles(conversationId) {
+    try { return (await this.c.runtime.api(this.c.agent, 'GET', `/v1/conversations/${encodeURIComponent(conversationId)}/files`)).files ?? []; }
+    catch (error) { throw this.apiError(error); }
+  }
+
+  apiError(error) {
+    if (error instanceof ApiError && error.unknownRoute) return new SafeError(fileErrors.noServer);
+    if (error instanceof ApiError && fileApiMessages[error.code]) return new SafeError(fileApiMessages[error.code]);
+    return this.c.failure(error);
+  }
+
+  expired(dto) { return dto.status === 'expired' || !(Date.parse(dto.expiresAt) > this.now()); }
+
+  /**
+   * Encrypt a local file and ask the sender's owner to approve it, then
+   * continue as far as the owner allows within `timeoutMs` (see advance).
+   */
+  async send(conversationId, path, { timeoutMs = 0 } = {}) {
+    const view = await this.active(conversationId);
+    const waiting = async () => (await this.vault.list('outgoing')).filter(r => !r.sent).length;
+    if (await waiting() >= MAX_PENDING_OUTGOING) {
+      // Ended transfers do not count: clean them up before refusing.
+      await this.sweep().catch(() => null);
+      if (await waiting() >= MAX_PENDING_OUTGOING) throw new SafeError(fileErrors.tooMany);
+    }
+    const bytes = await readSource(path);
+    let encrypted;
+    try { encrypted = await encryptFile({ name: basename(String(path)), bytes }); }
+    catch (error) { throw cryptoFailure(error); }
+    // Kept locally BEFORE the request, so a local write failure cannot leave a
+    // server record this runtime does not know (lbframe/wacando-agent#21).
+    const staged = await this.vault.stageCiphertext(encrypted.ciphertext);
+    let file;
+    try { ({ file } = await this.c.runtime.api(this.c.agent, 'POST', `/v1/conversations/${encodeURIComponent(view.id)}/files`, encrypted.approval)); }
+    catch (error) { await this.vault.dropStaged(staged); throw this.apiError(error); }
+    if (!FILE_ID.test(file?.id ?? '') || file.ciphertextSha256 !== encrypted.approval.ciphertextSha256 || file.sizeBytes !== encrypted.approval.sizeBytes) {
+      await this.vault.dropStaged(staged);
+      throw new SafeError('The server answered an unexpected file record. Nothing was sent.');
+    }
+    const record = {
+      fileId: file.id, conversationId: view.id, name: encrypted.name, mediaType: encrypted.mediaType,
+      size: encrypted.plaintextSize, sha256: encrypted.plaintextSha256, ciphertextSha256: encrypted.approval.ciphertextSha256,
+      ciphertextSize: encrypted.approval.sizeBytes, key: hex(encrypted.key), iv: hex(encrypted.iv),
+      requestedAt: new Date(this.now()).toISOString(), expiresAt: file.expiresAt,
+    };
+    try {
+      await this.vault.commitCiphertext(staged, file.id);
+      await this.vault.write('outgoing', file.id, record);
+    } catch {
+      // The server record stays pending without a review copy: it can never be
+      // approved; the owner can refuse it and it expires after 30 days.
+      await this.vault.dropStaged(staged);
+      await this.vault.remove('outgoing', file.id).catch(() => {});
+      throw new SafeError(fileErrors.orphan);
+    }
+    // Right after the request: the owner's review copy (retried by advance()).
+    return this.once(file.id, async () => {
+      const review = await this.review(record);
+      if (review.final) return review.final;
+      return this.advance(file.id, timeoutMs);
+    });
+  }
+
+  /**
+   * Deposit the review copy of a PENDING file for this agent's owner
+   * (PUT /v1/files/:id/review {stanza, ciphertext}, 201): the exact ciphertext
+   * the approval covers, and an OMEMO stanza encrypted for the owner's devices
+   * ONLY, whose body is the review descriptor (it carries the key). The stanza
+   * is kept in the private vault (0600) before the first PUT and resent
+   * byte-identical on retries (a re-encrypted stanza is a 409 for the server),
+   * then forgotten once the server confirmed the deposit. It is never posted
+   * in the room and never logged.
+   * Returns {done: true}, {note} (stays pending, retried later) or
+   * {final: result} (abandoned: the local copy and key are discarded).
+   */
+  async review(record) {
+    if (record.reviewed) return { done: true };
+    if (!record.reviewStanza) {
+      let stanza;
+      try { stanza = await this.sealReview(record); }
+      catch (error) { return { note: error instanceof SafeError ? error.message : fileErrors.reviewRetry }; }
+      if (!stanza) return { note: fileErrors.noOwnerDevice };
+      record.reviewStanza = stanza;
+      await this.vault.write('outgoing', record.fileId, record);
+    }
+    const ciphertext = await this.vault.readCiphertext(record.fileId);
+    if (!ciphertext) throw storageError();
+    let response;
+    try {
+      response = await this.fetch(new URL(`/v1/files/${encodeURIComponent(record.fileId)}/review`, this.c.agent.origin), {
+        method: 'PUT', redirect: 'error', credentials: 'omit', referrerPolicy: 'no-referrer', signal: AbortSignal.timeout(60000),
+        headers: { Authorization: `Bearer ${this.c.agent.agentToken}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ stanza: record.reviewStanza, ciphertext: Buffer.from(ciphertext).toString('base64') }),
+      });
+    } catch { return { note: fileErrors.reviewRetry }; }
+    let code;
+    try { code = (await response.json())?.error?.code; } catch { /* no JSON body */ }
+    // 201: deposited. CONFLICT: a copy is already there (only this agent can
+    // deposit one). INVALID_STATE_TRANSITION: no longer pending. A plain 404
+    // is an API without review copies, whose approval needs none.
+    if (response.status === 201 || REVIEW_DONE.has(code) || (response.status === 404 && code === undefined)) {
+      delete record.reviewStanza; // forgotten once the server holds it
+      record.reviewed = true;
+      await this.vault.write('outgoing', record.fileId, record);
+      return { done: true };
+    }
+    if (REVIEW_FINAL.has(code)) {
+      await this.discard(record);
+      const summary = publicOutgoing(record);
+      if (code === 'FILE_EXPIRED') return { final: { file: summary, state: 'expired', note: fileApiMessages.FILE_EXPIRED } };
+      if (code.startsWith('CONVERSATION_')) return { final: { file: summary, state: 'refused', reason: 'conversation_closed', note: fileErrors.notActive('closed') } };
+      return { final: { file: summary, state: 'refused', reason: 'review_refused', note: `${fileApiMessages[code]} The file was abandoned; nothing will be deposited.` } };
+    }
+    return { note: fileErrors.reviewRetry };
+  }
+
+  /**
+   * The review stanza (serialized XML) for the owner's devices only, or null
+   * when the owner has no device. Encrypted with the per-file key kept in the
+   * vault; the plaintext descriptor never leaves this function.
+   */
+  async sealReview(record) {
+    const view = await this.c.conversation(record.conversationId);
+    const owner = ownOwnerId(view, this.c.agent.agentId);
+    let body;
+    try { body = await this.c.runtime.api(this.c.agent, 'GET', `/v1/conversations/${encodeURIComponent(record.conversationId)}/recipients`); }
+    catch (error) {
+      if (error instanceof ApiError && error.code === 'SECURE_MESSAGING_UNAVAILABLE') return null;
+      throw this.apiError(error);
+    }
+    const jids = ownerReviewJids(body, record.conversationId, owner);
+    if (jids.length === 0) return null;
+    const { client, provider } = this.c.session;
+    let targets;
+    try { targets = (await provider.resolveDeviceTargets(client, jids)).filter(t => jids.includes(t.bareJid)); }
+    catch { return null; } // an owner device without published OMEMO keys
+    if (targets.length === 0) return null;
+    let text;
+    try {
+      text = formatFileReview(fileReviewFor({
+        key: unhex(record.key), iv: unhex(record.iv), name: record.name, mediaType: record.mediaType,
+        plaintextSize: record.size, plaintextSha256: record.sha256,
+        approval: { ciphertextSha256: record.ciphertextSha256, sizeBytes: record.ciphertextSize, mediaType: record.mediaType },
+      }, record.fileId));
+    } catch (error) { throw cryptoFailure(error); }
+    try { return (await provider.encryptForTargets(targets, this.c.room(record.conversationId), text)).toString(); }
+    catch { throw new SafeError('Secure messaging is unavailable: the review copy could not be encrypted for your owner. The file stays pending.'); }
+  }
+
+  /** State of a file of this agent (outgoing: advanced as far as allowed; incoming: quarantine state). */
+  async status(fileId, { timeoutMs = 0 } = {}) {
+    FileVault.id(fileId);
+    if (await this.vault.read('outgoing', fileId)) return this.once(fileId, () => this.advance(fileId, timeoutMs));
+    const incoming = await this.vault.read('incoming', fileId);
+    if (!incoming) throw new SafeError(fileErrors.unknown);
+    return this.incomingState(incoming, { timeoutMs, fetch: false });
+  }
+
+  once(fileId, run) {
+    const running = this.busy.get(fileId);
+    if (running) return running;
+    const task = run().finally(() => this.busy.delete(fileId));
+    this.busy.set(fileId, task);
+    return task;
+  }
+
+  async discard(record) {
+    await this.vault.remove('outgoing', record.fileId);
+  }
+
+  /**
+   * Outgoing state machine, bounded by `timeoutMs` (never blocks forever):
+   * pending -> (owner approves) -> slot + PUT -> descriptor message -> sent.
+   * Rejected, expired or a closed conversation discard the local copy and key.
+   */
+  async advance(fileId, timeoutMs) {
+    const deadline = this.now() + timeoutMs;
+    for (;;) {
+      const record = await this.vault.read('outgoing', fileId);
+      if (!record) throw new SafeError(fileErrors.unknown);
+      const summary = publicOutgoing(record);
+      const view = await this.c.conversation(record.conversationId);
+      if (view.state !== 'active') {
+        await this.discard(record);
+        return { file: summary, state: 'refused', reason: 'conversation_closed', note: fileErrors.notActive(view.state) };
+      }
+      const dto = (await this.serverFiles(record.conversationId)).find(f => f.id === fileId);
+      if (!dto || dto.ciphertextSha256 !== record.ciphertextSha256 || dto.sizeBytes !== record.ciphertextSize) {
+        await this.discard(record);
+        return { file: summary, state: 'refused', reason: 'unknown_on_server', note: 'The server no longer lists this file. Nothing more will be sent.' };
+      }
+      if (this.expired(dto)) {
+        await this.discard(record);
+        return { file: summary, state: 'expired', note: fileApiMessages.FILE_EXPIRED };
+      }
+      if (dto.status === 'rejected') {
+        await this.discard(record);
+        return { file: summary, state: 'rejected', note: 'Your owner refused this file in the Wacando app. Nothing was deposited.' };
+      }
+      if (record.sent) return { file: summary, state: 'sent', server: dto.status, messageId: record.messageId };
+      if (dto.status === 'pending') {
+        // The owner can approve only after reading the review copy: deposit it first.
+        const review = await this.review(record);
+        if (review.final) return review.final;
+        if (this.now() >= deadline) {
+          return { file: summary, state: 'awaiting_approval', reviewCopy: review.done ? 'deposited' : 'not_deposited',
+            ...(review.note ? { note: review.note } : {}),
+            next: `Ask your owner to approve this file in the Wacando app (fingerprint ${record.ciphertextSha256.slice(0, 16)}..., ${record.ciphertextSize} bytes), then call wacando_file_status. The request expires at ${dto.expiresAt}.` };
+        }
+        await this.sleep(Math.min(this.pollMs, Math.max(0, deadline - this.now())));
+        continue;
+      }
+      if (dto.status === 'approved') await this.deposit(record);
+      return this.announce(record, view);
+    }
+  }
+
+  /** XEP-0363 slot for the approved digest, then PUT the ciphertext to the pinned origin only. */
+  async deposit(record) {
+    const ciphertext = await this.vault.readCiphertext(record.fileId);
+    if (!ciphertext) throw storageError();
+    const session = this.c.session;
+    let slot;
+    try {
+      slot = await requestUploadSlot(session.client, uploadServiceJid(this.c.domain),
+        { filename: record.ciphertextSha256, size: record.ciphertextSize, contentType: 'application/octet-stream' }, 15000);
+    } catch { throw new SafeError(fileErrors.slot); }
+    checkSlot(slot, this.pin, record.fileId);
+    // Recorded BEFORE the PUT: a deposited file gets no second slot.
+    record.slotGet = slot.get;
+    await this.vault.write('outgoing', record.fileId, record);
+    let response;
+    try {
+      response = await this.fetch(new URL(new URL(slot.put).pathname, this.pin.origin), {
+        method: 'PUT', body: ciphertext, redirect: 'error', credentials: 'omit', referrerPolicy: 'no-referrer',
+        signal: AbortSignal.timeout(60000),
+        headers: { Authorization: `Bearer ${this.c.agent.agentToken}`, 'Content-Type': 'application/octet-stream' },
+      });
+    } catch { throw new SafeError('The encrypted file could not be deposited. Retry with wacando_file_status.'); }
+    let code;
+    try { code = (await response.json())?.error?.code; } catch { /* no JSON body */ }
+    if (response.status !== 201 && response.status !== 200) {
+      throw new SafeError(fileApiMessages[code] ?? `The server refused the deposit (HTTP ${response.status}). Retry with wacando_file_status.`);
+    }
+  }
+
+  /** Send the OMEMO descriptor (URL + key), then forget the key and ciphertext. */
+  async announce(record, view) {
+    if (pinnedUploadId(record.slotGet ?? '', this.pin) !== record.fileId) throw new SafeError(fileErrors.slot);
+    const share = fileShareFor({
+      key: unhex(record.key), iv: unhex(record.iv), name: record.name, mediaType: record.mediaType,
+      plaintextSize: record.size, plaintextSha256: record.sha256,
+      approval: { ciphertextSha256: record.ciphertextSha256, sizeBytes: record.ciphertextSize, mediaType: record.mediaType },
+    }, record.slotGet);
+    const memo = { file: { ...publicOutgoing(record), state: 'sent' } };
+    const result = await this.c.deliver(view, formatFileShare(share), memo);
+    // Keep only public metadata: the key and the ciphertext are forgotten.
+    await this.vault.dropCiphertext(record.fileId);
+    const { key: _key, iv: _iv, reviewStanza: _review, ...kept } = record;
+    await this.vault.write('outgoing', record.fileId, { ...kept, sent: true, messageId: result.message.id });
+    return { file: publicOutgoing(record), state: 'sent', message: result.message, conversation: result.conversation,
+      note: result.message.state === 'held' ? "The file is deposited; its message waits for your owner's approval (service mode)." : 'Deposited and shared. The recipient gets it only after its owner authorizes it.' };
+  }
+
+  /**
+   * A decrypted message body claiming to be a file share (peer side): parsed
+   * strictly against the PINNED origin, then kept in quarantine. Returns the
+   * public summary placed in the transcript entry instead of the text.
+   */
+  async intake(conversationId, messageId, body) {
+    let share;
+    try { share = parseFileShare(body, this.pin); } catch { return { state: 'refused', reason: 'invalid_descriptor', note: fileErrors.descriptor }; }
+    const fileId = shareFileId(share);
+    if (!fileId) return { state: 'refused', reason: 'invalid_descriptor', note: fileErrors.descriptor };
+    const known = await this.vault.read('incoming', fileId);
+    if (known) {
+      if (known.conversationId !== conversationId || known.ciphertextSha256 !== share.ciphertextSha256) {
+        return { state: 'refused', reason: 'duplicate_descriptor', note: fileErrors.descriptor };
+      }
+      return { ...publicIncoming(known), state: known.path ? 'received' : 'quarantined' };
+    }
+    if ((await this.vault.list('incoming')).filter(r => !r.path).length >= MAX_QUARANTINED_INCOMING) {
+      return { state: 'refused', reason: 'too_many_quarantined', note: fileErrors.tooManyIncoming };
+    }
+    const record = { fileId, conversationId, messageId, share, ciphertextSha256: share.ciphertextSha256, receivedAt: new Date(this.now()).toISOString() };
+    await this.vault.write('incoming', fileId, record);
+    return { ...publicIncoming(record), state: 'quarantined', note: `In quarantine until your owner authorizes it; then call wacando_receive_file. ${UNTRUSTED}` };
+  }
+
+  /** Fetch a released incoming file into the quarantine directory (bounded wait for the release). */
+  async receive(fileId, { timeoutMs = 0 } = {}) {
+    const record = await this.vault.read('incoming', FileVault.id(fileId));
+    if (!record) throw new SafeError(fileErrors.unknown);
+    return this.once(fileId, () => this.incomingState(record, { timeoutMs, fetch: true }));
+  }
+
+  async incomingState(record, { timeoutMs, fetch }) {
+    const summary = publicIncoming(record);
+    if (record.path) return { file: summary, state: 'received', path: record.path, note: `${UNTRUSTED} ${KEPT}` };
+    const deadline = this.now() + timeoutMs;
+    for (;;) {
+      const view = await this.c.conversation(record.conversationId);
+      if (view.state !== 'active') {
+        // STOP is terminal: this agent can never fetch it; drop the key.
+        await this.vault.remove('incoming', record.fileId);
+        return { file: summary, state: 'refused', reason: 'conversation_closed', note: fileErrors.notActive(view.state) };
+      }
+      const dto = (await this.serverFiles(record.conversationId)).find(f => f.id === record.fileId);
+      if (!dto || dto.recipientAgentId !== this.c.agent.agentId || dto.ciphertextSha256 !== record.share.ciphertextSha256 ||
+          dto.sizeBytes !== record.share.ciphertextSize || dto.mediaType !== record.share.mediaType) {
+        await this.vault.remove('incoming', record.fileId);
+        return { file: summary, state: 'refused', reason: 'not_approved_file', note: 'The server does not list this file as approved for this agent. It was refused and never fetched.' };
+      }
+      if (this.expired(dto)) {
+        await this.vault.remove('incoming', record.fileId);
+        return { file: summary, state: 'expired', note: fileApiMessages.FILE_EXPIRED };
+      }
+      if (dto.status === 'released' && fetch) return this.fetchReleased(record, dto, summary);
+      if (dto.status === 'released') return { file: summary, state: 'released', next: 'Your owner authorized it: call wacando_receive_file to fetch it into the quarantine directory.' };
+      if (this.now() >= deadline || !fetch) {
+        return { file: summary, state: 'quarantined', server: dto.status,
+          next: "The file stays in quarantine until your owner authorizes it in the Wacando app; then call wacando_receive_file." };
+      }
+      await this.sleep(Math.min(this.pollMs, Math.max(0, deadline - this.now())));
+    }
+  }
+
+  async fetchReleased(record, dto, summary) {
+    let file;
+    try {
+      const ciphertext = await downloadFile(record.share, { pin: this.pin, bearer: this.c.agent.agentToken, fetch: this.fetch });
+      file = await decryptFile(ciphertext, record.share, { approvedCiphertextSha256: dto.ciphertextSha256 });
+    } catch (error) { throw cryptoFailure(error); }
+    const path = await this.vault.place(record.fileId, file.name, file.bytes);
+    const kept = { fileId: record.fileId, conversationId: record.conversationId, messageId: record.messageId, name: quarantineName(file.name),
+      mediaType: file.mediaType, size: file.bytes.length, ciphertextSha256: record.share.ciphertextSha256, path, receivedAt: record.receivedAt };
+    // The key is no longer needed once the plaintext is written: forget it.
+    await this.vault.write('incoming', record.fileId, kept);
+    return { file: { ...publicIncoming(kept) }, state: 'received', path, sha256: record.share.sha256, note: `${UNTRUSTED} ${KEPT}` };
+  }
+
+  /** Local file transfers of this identity (optionally one conversation), no keys; ended transfers are cleaned up first. */
+  async list(conversationId) {
+    const cleaned = await this.sweep().catch(() => null);
+    const keep = r => !conversationId || r.conversationId === conversationId;
+    return {
+      outgoing: (await this.vault.list('outgoing')).filter(keep).map(r => ({ ...publicOutgoing(r), state: r.sent ? 'sent' : r.slotGet ? 'deposited' : 'awaiting_approval' })),
+      incoming: (await this.vault.list('incoming')).filter(keep).map(r => ({ ...publicIncoming(r), state: r.path ? 'received' : 'quarantined', ...(r.path ? { kept: true } : {}) })),
+      ...(cleaned && (cleaned.outgoing || cleaned.incoming) ? { cleaned } : {}),
+    };
+  }
+
+  /**
+   * Delete the local secrets of every transfer that can never continue
+   * (lbframe/wacando-agent#21), at connection and before each listing:
+   * - pending/deposited sends (ciphertext + key) and quarantined descriptors
+   *   (key): conversation no longer active (STOP is terminal) or unknown to
+   *   the server, file unknown, different, rejected or expired on the server,
+   *   or past its 30-day expiry by the local clock (even offline);
+   * - sent records (public metadata only, no key): past their expiry;
+   * - interrupted-write leftovers older than an hour.
+   * A received file (written to the quarantine directory) and its record are
+   * never touched. A server that cannot be reached removes nothing it cannot
+   * decide locally. Transfers in progress in this process are skipped.
+   * Returns content-free counts.
+   */
+  sweep() {
+    this.sweeping ??= this.sweepOnce().finally(() => { this.sweeping = null; });
+    return this.sweeping;
+  }
+
+  async sweepOnce() {
+    const now = this.now();
+    const counts = { outgoing: 0, incoming: 0 };
+    const servers = new Map(); // conversationId -> Promise<{state, files} | null>
+    const server = id => {
+      if (!servers.has(id)) servers.set(id, this.serverState(id));
+      return servers.get(id);
+    };
+    for (const direction of ['outgoing', 'incoming']) {
+      for (const record of await this.vault.list(direction)) {
+        if (direction === 'incoming' && record.path) continue; // received: the user's file
+        if (this.busy.has(record.fileId)) continue;
+        if (!(await this.ended(direction, record, now, server))) continue;
+        if (this.busy.has(record.fileId)) continue;
+        await this.vault.remove(direction, record.fileId);
+        counts[direction]++;
+      }
+    }
+    await this.vault.dropLeftovers(now - STALE_LEFTOVER_MS).catch(() => 0);
+    return counts;
+  }
+
+  /** Conversation state and files as the server lists them for this agent; 'gone' when unknown; null when unreachable. */
+  async serverState(conversationId) {
+    let state;
+    try { state = (await this.c.runtime.api(this.c.agent, 'GET', `/v1/conversations/${encodeURIComponent(conversationId)}`))?.conversation?.status; }
+    catch (error) { return error instanceof ApiError && error.code === 'NOT_FOUND' ? { state: 'gone' } : null; }
+    if (typeof state !== 'string') return null;
+    if (state !== 'active') return { state };
+    try { return { state, files: await this.serverFiles(conversationId) }; } catch { return null; }
+  }
+
+  async ended(direction, record, now, server) {
+    // The server's expiry, else 30 days after the local request or receipt
+    // (a file is requested before it is received: never earlier than the server).
+    const started = Date.parse(record.receivedAt ?? record.requestedAt ?? '');
+    const expiresAt = Date.parse(record.expiresAt ?? '') || started + FILE_RETENTION_MS;
+    if (expiresAt <= now) return true;
+    if (direction === 'outgoing' && record.sent) return false; // no key left; kept until its expiry
+    const known = await server(record.conversationId);
+    if (!known) return false;
+    if (known.state !== 'active') return true;
+    const dto = known.files.find(f => f.id === record.fileId);
+    if (!dto || this.expired(dto)) return true;
+    if (direction === 'outgoing') return dto.ciphertextSha256 !== record.ciphertextSha256 || dto.sizeBytes !== record.ciphertextSize || dto.status === 'rejected';
+    return dto.recipientAgentId !== this.c.agent.agentId || dto.ciphertextSha256 !== record.share?.ciphertextSha256;
+  }
+}
+
+/** Read a local regular file (no symlink), size-checked BEFORE reading. */
+async function readSource(path) {
+  if (typeof path !== 'string' || !path) throw new SafeError(fileErrors.unreadable);
+  let file;
+  try {
+    const stat = await lstat(path);
+    if (!stat.isFile()) throw new SafeError(fileErrors.unreadable);
+    if (stat.size > MAX_FILE_PLAINTEXT_BYTES) throw new SafeError(fileErrors.tooLarge);
+    file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const opened = await file.stat();
+    if (!opened.isFile()) throw new SafeError(fileErrors.unreadable);
+    if (opened.size > MAX_FILE_PLAINTEXT_BYTES) throw new SafeError(fileErrors.tooLarge);
+    const bytes = await file.readFile();
+    if (bytes.length > MAX_FILE_PLAINTEXT_BYTES) throw new SafeError(fileErrors.tooLarge);
+    return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.length);
+  } catch (error) {
+    throw error instanceof SafeError ? error : new SafeError(fileErrors.unreadable);
+  } finally { await file?.close(); }
+}