diff --git a/docs/commons-files-desk.md b/docs/commons-files-desk.md index 9956cc60..f11abb9e 100644 --- a/docs/commons-files-desk.md +++ b/docs/commons-files-desk.md @@ -1,6 +1,6 @@ # Files desk: Commons and per-Persona file zones -Status: design only. No code, nothing deployed. Items marked **UNKNOWN** are not verified against the Body; **Q-E** / **Q-M** are open questions for Eureka (host) and Meta (audience, uploads), collected at the end. +Status: design only. No code, nothing deployed. Items marked **UNKNOWN** are not verified against the Body; **Q-E** / **Q-M** are open questions for Eureka (host) and Meta (audience, names), collected at the end. Source: Meta, #swarm 2026-11-13 14:28Z; ruling `ratatoskr:ruling:persona-file-sharing-zone` (each Persona has her own file sharing zone the frontend shows: a browsable, previewing collection; the Self writes to her outbox, her Persona decides what is shared, the Self never holds Matrix credentials). @@ -48,7 +48,7 @@ The host is a service on Yggdrasil that Eureka owns. The client holds no filesys - `path` is `/`, with the zone one of the names the host announces. The host resolves the real path of every request and refuses anything that leaves the zone's root: `..`, absolute paths, NUL, symlinks that cross the root, dotfiles, and `handoff-private`, which is not on any allowlist. Errors are typed (`401 unauthenticated`, `403 zone not allowed`, `404`, `416`), and a path outside the allowlist is 404, not 403, so it says nothing about what exists. - **Auth: Matrix OpenID.** The client calls `mx.getOpenIdToken()` (already used in `CallWidgetDriver.ts`) and sends it as `Authorization: Bearer `. The host verifies it against the homeserver's federation `openid/userinfo` endpoint, **pinned to our server name** (an `@void:evil.example` token must fail), caches the verified `sub` for the token's lifetime, and derives the role. It never sees the user's access token, and a Mind's Self never holds a token (ruling above): Minds reach the same bytes through the filesystem or the mouth, not this host. - **Role** in the response: `member`, `mind`, `steward` (host decides from the Matrix id and the room/space membership the host reads; the client trusts none of it for access). **Q-E:** exact source of membership (estate Space membership read by the host with a service account, versus the Persona catalogue file for Minds). -- **Uploads, only if Meta approves (Q-M):** `PUT /file?path=

` with `Content-Length` required, a hard per-file cap (suggest 25 MiB; the existing Matrix limit is `m.upload.size` and the mouth fetches at most 5 MiB), no overwrite (409), into a single `inbox/` directory per zone, `201` with the stored name, size and hash, and the same path and sniff rules. Without approval the host serves no `PUT` and the client has no upload control; the `role` field is what would gate the control. The Matrix zone already carries uploads (`ShareSet`), so the Files desk does not need them to be useful. +- **Uploads** (Meta approved for members and Minds, #swarm 2026-11-13 14:30Z; rules are Eureka's, below). `PUT /file?path=

` writes only under an `uploads/` subtree of a zone, with `Content-Length` required; the host enforces a size cap, a type allowlist (sniffed, not the client's claim), no overwrite unless the request carries an explicit flag, and never replaces a file a Mind wrote into the handoff tree; every write is audit-logged with the caller's Matrix id. Reads cover the whole allowlisted tree, so an uploaded file is listed like any other. Success is `201` with the stored name, size and hash. The `role` in the index response gates the upload control; the host gates the write. ### The one problem the contract leaves: media elements cannot send headers @@ -60,11 +60,47 @@ The host is a service on Yggdrasil that Eureka owns. The client holds no filesys Recommendation: 2 for audio and video, 1 for images and text. Confidence moderate: I have not tested a service worker against range requests on the target phone, and 2 is the usual answer for authenticated media (signed URLs). **Q-E.** +## Upload flow + +Design only. Every number and error code is a named placeholder until Eureka gives them on the PR: `` (per-file size), `` (per-pick total, if any), `` (the allowlist), `` (the explicit query flag), and the codes ``, ``, ``, ``, ``, ``, ``, ``, ``. + +**Where.** The control exists only where an upload is allowed: inside a folder under a zone's `uploads/` subtree (or at the `uploads/` row itself), and only when the index `role` is member or mind. Elsewhere there is no button; the list does not carry a disabled one. A folder outside `uploads/` shows a one-line dim note, "Uploads go in uploads/", which links to that folder. Creating subfolders under `uploads/` is not in this design (**Q-E8**). + +**Pick or drop.** One `Upload` row at the top of an `uploads/` folder opens the native picker (any number of files; on a phone this is the OS file sheet, camera roll included). On wide screens the list is also a drop target; the drop highlight appears only while a drag is over it. Nothing starts on pick: the picked files appear as a staging list (name, size, a type icon) with `Upload` and `Cancel` as full-width rows, as `ShareSet` does for a Matrix set. Files that already fail the client's cheap checks (over ``, a type outside ``) are marked in the staging list with the reason and left out of the send; the client mirrors the cap and allowlist as a courtesy only, the host is the authority, and the list is read from the host (**Q-E9**: an `/index` field or a `/limits` call) rather than hard-coded. + +**Send.** Files go one at a time, in pick order, each a `PUT /file?path=/` with the bearer token. One at a time keeps a phone on mobile data from starving every transfer, and a refusal names exactly one file. The transport is `XMLHttpRequest`, not `fetch`: `fetch` has no upload progress and the row needs it. The body is the `File` itself (streamed by the browser, not read into memory; unlike the Matrix path, the client computes no hash first, the host returns one). The name is the file's own name, with path separators and control characters replaced, never a path the user typed. + +**Progress.** The staging list becomes the progress list: per file a thin bar and "412 KB of 3.1 MB", per batch "2 of 5". Finished files show a tick and the stored name; refused ones show the refusal in place; waiting ones are dim. Only the active file animates. The list stays on screen after the last file until dismissed, so a refusal is not lost to a refresh of the folder underneath it. The folder listing refetches after each success, so the file appears in the list as it lands. + +**Cancel.** `Cancel` on the active file aborts the request (`xhr.abort()`) and goes on to the next; `Cancel all` on the batch aborts the active file and drops the rest. The host must discard an aborted partial write and never leave a half file in the listing (**Q-E10**, written to a temporary name and renamed on completion). Leaving the page aborts whatever runs, as the Matrix share does; the client does not resume. + +**Overwrite.** A name that already exists is refused with `` and shown as " is already there". A `Replace` row appears under that refusal only for a file the caller wrote themselves, and sends the same `PUT` with ``; a Mind-written handoff file refuses with `` and offers only "Keep both", which re-sends under a suffixed name (`name (2).ext`) chosen by the client. Whether the client can tell "mine" from the index (an `owner` field with the Matrix id) or learns it only from the refusal is **Q-E11**; absent an owner field, `Replace` is simply offered after `` and the host's answer decides. + +**Refusal messages.** One plain sentence per code, shown in the file's row; nothing says "error" without saying why, and none names a server path. + +| Code | Message (draft) | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| `` | Sign-in expired. Reload to upload again. (The client fetches a fresh OpenID token once and retries before showing this.) | +| `` | Uploads are for members and Minds. | +| `` | That folder does not take uploads. | +| `` | "" is a file; allowed types are . | +| `` | "" is ; the limit is . | +| `` | "" is already there. | +| `` | "" was written by a Mind and cannot be replaced. | +| `` | The shared space is full. Tell a steward. | +| `` / network / timeout | Could not reach the file host. The file was not saved. | + +Retry is one tap on a failed row; the batch never retries on its own. An unknown code shows the host's status text as it is, still without a path. + +**Honest end state.** Done means the host answered `201` and the stored name, size and hash are shown. "Saved" is not said earlier; the hash the host returns is displayed so a sender can compare it with their own. + +**Reuse and not.** `ShareSet`'s state machine (staging, one-send-per-zone guard, failed files kept by position) is the model, but the Matrix share path and its `createUploadAtom` are tied to the SDK's media upload and are not reused; the new controller sits in `features/files/uploadController.ts` with the same injected-port shape, so order, refusal and cancel rules are tested against a fake `PUT` without a browser. Real transfer progress and a real range of a phone's picker stay a phone check. + ## Client shape Under `src/app/features/files`, mirroring `features/albums`: -- `filesHost.ts`: ports, `list(path)`, `url(path)`, `ticket(path)`; the only module that knows the contract. Injected, so the UI is tested against a fake and the real client never runs in a test. +- `filesHost.ts`: ports, `list(path)`, `url(path)`, `ticket(path)`, `put(path, file, onProgress, signal)`; the only module that knows the contract. Injected, so the UI is tested against a fake and the real client never runs in a test. - `useFilesZone.ts`: react-query on `['files', zone, path]`, `staleTime` 30 s; the role comes with every index. - `FilesDesk.tsx`, `FileRow.tsx`, `FilePreview.tsx`: pure rendering from the above; the preview picks its renderer from the host's `mime`, not the extension. - `config.json`: `filesDesk: { enabled: false, host: "https://…" }`, dark by default as `fileZoneShare.enabled` is. With it off, no row mounts and no request leaves the client. @@ -76,7 +112,7 @@ Under `src/app/features/files`, mirroring `features/albums`: 2. **Read-only Commons desk**: route, row, list, breadcrumb, role display, flagged off. 3. **Preview and player**: image, audio with ranges, text, video; the ticket if Q-E settles on 2. 4. **Per-Persona rows** in each Mind's group, once the outbox `shared/` convention and the zone provisioning exist. -5. **Uploads**: only on Meta's yes. +5. **Uploads**: the flow above; needs Eureka's codes and caps and the host's `PUT`. Each is its own PR. Slices 1 to 3 need no host to build and test; slice 2 needs the real host to be useful, not to land. @@ -95,11 +131,15 @@ The Matrix file zone (marks, receipts, `ShareSet`); any Mind-side fetch (the mou - **Q-E5.** Per-Persona publishing: a `shared/` subdirectory versus a marker, and who populates it when the Persona decides. - **Q-E6.** Hash cost: compute lazily and cache by (path, mtime, size), or at publish time. - **Q-E7.** CORS for `chat.gamecult.org` and the dev previews, rate limits, and the `Content-Disposition` list. +- **Q-E8.** Subfolders under `uploads/`: can a client create them (by a `PUT` path that implies them, or a `MKCOL`-like call), or is `uploads/` flat? +- **Q-E9.** Cap and allowlist discovery: fields in the index response, or a `/limits` endpoint; and the exact codes and cap numbers behind every placeholder in the upload flow. +- **Q-E10.** Partial writes: temporary name then rename, so an aborted or failed upload never appears in a listing. +- **Q-E11.** Does the index carry an `owner` Matrix id per file (so `Replace` is offered only on one's own files), and is the audit log readable by stewards from the client or only on the host? **For Meta:** - **Q-M1.** Audience: Commons for members and Minds as proposed; are Users and Patrons ever in (the Matrix zone's audience question, `ratatoskr:question:file-zone-audience`, is the same fork)? - **Q-M2.** Is a Persona's zone visible to all members or to her stewards and Minds? -- **Q-M3.** Uploads: yes or no, and if yes, who (members, Minds, stewards) and the cap. +- **Q-M3.** ~~Uploads~~ approved for members and Minds (2026-11-13 14:30Z); open only: may Users or Patrons upload if they are ever let in? - **Q-M4.** Name: "Files" for the row, "Commons" for the shared zone. - **Q-M5.** Does the Matrix Media row stay beside the Files row on each Mind, or does one absorb the other once the Files desk exists (recommendation: both stay; marks and receipts are Matrix's).