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
24 changes: 21 additions & 3 deletions FSD/CSD/CSD-007-files.md
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,22 @@ Tags: `file_preview_text`, `file_not_rendered`, `file_save_blocked`,
`file_unreadable`, `file_digest_verified`, `file_digest_not_sent`,
`file_policy_builtin`.

**The receipt's acts.** Every file row's receipt offers Open and *Where is this
file* (CSD-107), then the author's acts: **Rename** (`dialog_file_rename`),
**Move** (`dialog_file_move`: Just me, or another room this circle lists) and
**Withdraw** (`dialog_file_withdraw`). The node allows them to the author only
and refuses anyone else by id; the outcome is a named line
(`dialog_file_act_result`), never a silent success. In a room (the files panel
of CSD-091 and CSD-110) the receipt adds the moderation acts on the file's
AUTHOR (CSD-065: *Moderate the author*, *Flag the author*; unavailable with
"only a moderator of this room" for anyone else) and two acts drawn
unavailable with their blockers: *Take down (legal basis)* (CIRISPersist#1160)
and *Report to the room's moderators* (CIRISServer#665). An unavailable act is a
dim chip that says why when tapped (`receipt_act_unavailable`); it never acts.

**One room's files.** The same card, in room mode, is the files panel of a chat
room: it lists exactly that room (`cohort=community&room_id`) and adds into it.

## 3. Contracts (who)

Sources: CIRISServer `v0.5.217` and `v0.5.218`, `src/drive.rs` and
Expand All @@ -201,15 +217,17 @@ version. Rows marked "not called" are live on the node and not wired here.
| this owner's key, so the roster can say "you" | `GET /v1/setup/owned-nodes` | CIRISServer (CSD-100 §3) | called — `api/HouseholdsApi.kt:86`, by the shared household model |
| which of the person's devices the file is on | `GET /v1/files/{id}/custody?cohort&room_id` | CIRISServer v0.5.218 `src/drive.rs:3921` (handler `:2548`, the same `FileQuery`); 0.5.217 answers a bare 404 | called — `ui/screens/files/FilesScreen.kt:332`, from the row receipt's **Where is this file** act (`btn_receipt_act_where_<id>`), with the same `fileQuery`; the card is CSD-107's |
| everything about a file except its bytes, **including `content_digest`** | `GET /v1/files/{id}/meta` | CIRISServer `src/drive.rs:3017` (handler `:1872`; digest `:1917-1921`, `:1951-1952`; costs a whole read, so it is computed here and on open, never per listed row) | live, **not called** — the card opens the bytes to learn what a meta read would say |
| rename | `POST /v1/files/{id}/rename` | CIRISServer `src/drive.rs:3018` (handler `:2272`) — a new row over the SAME bytes, old row withdrawn, author only | live, **not called** |
| move to another circle ("going out asks": this call IS the ask) | `POST /v1/files/{id}/move` `{…, keep_source}` | CIRISServer `src/drive.rs:3019` (handler `:2465`) — reseals at the target room's tier; author only, and a member of the target | live, **not called**. This is the cross-circle move the Files tab needs; `keep_source: true` is "share to" |
| replace a file's bytes | `PUT /v1/files/{id}` | CIRISServer `src/drive.rs:3013` (handler `:2186`) — publishes the new row THEN withdraws the old | live, **not called** |
| withdraw a file | `DELETE /v1/files/{id}` | CIRISServer `src/drive.rs:3014` (handler `:2408`) — persist then refuses every read of the bytes (CC 2.3); holders drop it on their next pass | live, **not called** — the card has no delete |
| fetch content from a named peer by SHA-256 | `POST /v1/federation/content/{content_id}` | CIRISServer `src/federation_surface.rs:699`, owner-gated | live — called from the network hub's Content tile (`NetworkContentViewModel`, CSD-051 §3), not from Files. CIRISServer#651's "fetch" half; the directory half is the filed gap |
| a digest signed into the row; the listing's descriptor (digest, size, renditions, placeholder) | `GET /v1/drive` rows | CIRISEdge `blocked_by: CIRISEdge#638` (`src/drive.rs:170-172`) | blocks `receipt_dimension` on the receipt; the opened file is verified without it |
| renditions (display / thumb / poster) | the ingest pipeline; `derived_from` index (V149) | CIRISServer `blocked_by: CIRISServer#614`; the node says so itself (`renditions: false`) | Tier A media waits on it, and the sheet says so |
| a file above the whole-read cap (0.5.218) | `GET /v1/files/{id}` → 413 `drive.too_large_for_whole_read` (above `WHOLE_READ_CAP`, 64 MiB) | CIRISServer (`src/drive.rs::too_large_for_whole_read`) | **0.5.218, rendered** as a named state, not an error: `OpenState.TooLarge` → `file_too_large`, "This file is too large to open on this device yet." The bytes are there and open for this viewer; the client reads files whole and has no streaming read (`?raw=1`, which the server serves with `Range`) — not built here. Pinned: `FilesViewModelTest.aFileAboveTheWholeReadCapIsNamedTooLargeNotAFailure` |
| a file whose key has not arrived (0.5.220) | `GET /v1/drive` row `bytes: "awaiting_key"`; `GET /v1/files/{id}` → 409 `drive.awaiting_key` | CIRISServer `src/drive.rs` (`BYTE_STATES`, `blob_state`: persist `ChunkKeyNotYetGranted`, edge `UnopenedReason::AwaitingKey`; `refuse_state`) | **rendered** as a named wait, not an error: the row's line "Waiting for this file's key"; the sheet `file_awaiting_key`, "Waiting for this file's key" + "Its bytes are on this device, but the key that opens them hasn't arrived yet. It comes on its own; nothing is wrong.", with `btn_file_check_again` re-opening the file. Pinned: `FilesViewModelTest.aFileWhoseKeyHasNotArrivedIsAWaitingStateAndCheckAgainOpensIt`, `DriveWireTest.aKeyNotYetHereComesBackAsTheAwaitingKeyIdNotABare409` |
| rename a file you wrote | `POST /v1/files/{id}/rename {filename}` | CIRISServer `src/drive.rs` `rename_file` | **live** (0.5.242): a new row over the same bytes, the old withdrawn. Author only. The receipt's `btn_file_act_rename_{id}` → `dialog_file_rename` |
| move (or copy) a file you wrote ("going out asks": this call IS the ask) | `POST /v1/files/{id}/move {cohort, room_id?, keep_source}` | CIRISServer `move_file` | **live** (0.5.242): resealed at the target room's tier, the source withdrawn unless kept. Author only, and a member of the target. `dialog_file_move` offers Just me and this circle's other rooms |
| withdraw a file you wrote | `DELETE /v1/files/{id}?cohort&room_id` | CIRISServer `withdraw_file` | **live**, called. Author only; persist then refuses every read of the bytes (CC 2.3) and holders drop it on their next pass. The confirm (`dialog_file_withdraw`) says the others in the room no longer see it |
| a moderator's takedown of a FILE by legal basis | none yet | CIRISPersist · CIRISServer | **blocked_by CIRISPersist#1160** (persist's signer check cannot authorize a fed-ID moderator); drawn as the unavailable `btn_file_act_takedown_{id}` with that reason |
| report a file to the room's moderators | none yet | CIRISServer | **blocked_by CIRISServer#665**; drawn as the unavailable `btn_file_act_report_{id}` (CSD-128 is the protected reporter channel) |

Refusals arrive as `{error: <id>, detail: <english>}`; `NodeRefusal.fromBody`
reads the id from `error` when it is dotted. The `drive.*` ids are localized.
Expand Down
25 changes: 25 additions & 0 deletions FSD/CSD/CSD-065-moderation.md
Original file line number Diff line number Diff line change
Expand Up @@ -267,6 +267,28 @@ real**. The `why` column is why a flow cannot go without it.
| `txt_ladder_limits_unavailable` | the missing-bundle fallback | a limit the app cannot state is its own fact; it is tagged as such wherever a limit block falls back |
| `txt_ladder_catalogue_fallback` | the compiled ladder standing in | a compiled ladder shown as the node's is the drift `/v1/operations` exists to end |
| `chip_ladder_delegation_{i}` / `txt_ladder_delegations_*` | the owner's usable delegation ids, or why there are none | the id every act is taken under, from the node, not from a paste |
| `card_moderation_flag` / `btn_flag_subject` / `txt_flag_id` | the Flag card, its send, and the returned attestation id | the only evidence a flag was recorded; the card says a flag hides nothing yet |
| `txt_file_takedown_unavailable` | "taking a file down by legal basis isn't available yet" | a blocked act (CIRISPersist#1160) is said, not left out |

### 2.4 Flags, and moderation from an item's menu

**The Flag card** (`POST /v1/safety/flag`, CC 4.5.13): a moderator records that
a subject key's content was `reported` or is an `infohazard` in this community,
or clears an earlier flag. The node admits it only from a holder of the
`moderate` duty and refuses anyone else 403, rendered by id. **A flag is
recorded and hides nothing yet**: no listing, file read or transcript honours it
before ciris-server 0.5.243, and the card says so.

**From an item's menu.** A chat message's ⋮ (CSD-091) and a room file's receipt
(CSD-007) offer *Moderate the author* and *Flag the author*. Both open this
screen with the report and flag forms prefilled (`SafetyViewModel.prefillFromItem`):
the community is the room, the target and the flag subject are the item's
AUTHOR key, because moderation events and flags are about keys. For a viewer who
does not hold `moderate` in the room they are drawn unavailable, "only a
moderator of this room". Moderating another member's room file (withdrawing or
hiding it) **does not work yet**: no route lets a moderator withdraw a file they
did not author, and no read consults moderation events (§3).


## 3. Contracts (who)

Expand Down Expand Up @@ -300,6 +322,9 @@ The line numbers above are 0.5.217's; on `integ/0.5.218` the admin rungs are at
byte-identical.
| the candidate's track record | **missing** — the verdict body carries `candidate_key_id`, not `moderation_track_record` | CIRISServer | blocks `row_named_moderator_candidate` |
| **anyone-may-propose** (CC 4.5.13) | `POST /v1/safety/reports` — **missing** | CIRISServer | `blocked_by: CIRISServer#665`. The client calls it (`CIRISApiClient.proposeModeration`, on the NODE url); `src/safety/report.rs` is specified in CIRISServer `FSD/MODERATION_CHILD_SAFETY.md` §4.4 and does not exist on `origin/main` or `integ/0.5.218` (`src/safety/` is six files, no `report.rs`; no route literal). The sheet says so in words (§2.2) |
| flag or clear a subject | `POST /v1/safety/flag {signer_key_id, community_key_id, subject_key_id, content_class: infohazard\|reported, action: flag\|clear}` | CIRISServer `src/safety/infohazard.rs` `flag` | **live, recorded only** (CC 4.5.13): duty-gated, a non-moderator is refused 403. The row is written, but no reader honours it yet: `GET /v1/drive`, `GET /v1/files/{id}` and the chat transcript still list, serve and show flagged content (the read side is planned for 0.5.243: a `moderation` object on flagged entries, the bytes or body behind a reveal). The card says it does not hide anything. `card_moderation_flag`; reached also from a chat message's or room file's menu, prefilled with the room and the author (`SafetyViewModel.prefillFromItem`) |
| moderate another member's room file (withdraw / hide) | the moderation event above, on the file's author | CIRISServer | **does not work yet**: no route lets a moderator withdraw or hide a file they did not author (withdraw is author-only), and moderation events are not consulted by any read. Planned for 0.5.243 with the flag read side |
| take down a file by legal basis (withheld or destroyed on every node, counter-notice, then delete) | none yet | CIRISPersist · CIRISServer | **blocked_by CIRISPersist#1160**; `txt_file_takedown_unavailable` says so on the card |

**The last row is the gap that matters.** The only moderation path CC opens to a
member who holds no duty has no route behind it. The control is built, the
Expand Down
36 changes: 32 additions & 4 deletions FSD/CSD/CSD-091-user-chat.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,8 +133,8 @@ fields:
- ceg: x_private:op_disabled_reason
use: display-only
type: string
example: "mobile.chat_op_withdraw_unavailable"
renders: "Withdraw / Recant / Supersede are SHOWN AND DISABLED with their reason, not hidden and not fake-enabled: each needs the author's own hybrid signature over an envelope naming the target, an owner bearer session is not that signature, and the node exposes no route that would produce one (Attestation.kt:224-236). The object really does have the verb"
example: "mobile.chat_op_no_route"
renders: "Replace / Withdraw / Recant are enabled exactly where the row's `viewer_ops` lists them (the node's judgement: author-only, live-only; the node signs as the author with the person key it holds). Otherwise they are SHOWN AND DISABLED with the node's reason, never hidden: no `viewer_ops` → 'This node can't do this yet' (`mobile.chat_op_no_route`); listed without the op → 'Only the person who wrote this message can do this, and only while it's live' (`mobile.chat_op_not_permitted`)"
tag: "chat_msg_*"
- ceg: x_private:draft_bytes
use: display-only
Expand Down Expand Up @@ -189,6 +189,29 @@ transcript as a neutral system note, because `RoomHandshake::note` has three
consumers by design. A person who tries to send early sees one fact twice: once
as a failure, once as a note.

**History and revisions.** A message's ⋮ offers History: its lifecycle — the
original, then each replacement, withdrawal or recantation, with who signed it
and when (`GET …/history`; on a node without the route, the row's own record,
marked incomplete, never a one-row history). Replace puts the text back in the
composer (`chat_editing_banner`) and Send writes a supersede; Withdraw and
Recant confirm with three facts and an optional reason code that everyone in
the room can see (`dialog_chat_withdraw`, `dialog_chat_recant`). All three are
enabled only where the row's `viewer_ops` lists them.

**The room's files.** `btn_chat_files` opens `chat_room_files_panel`: the Files
card (CSD-007) for exactly this room, with add, open, *Where is this file*
(CSD-107), and the author's rename, move and withdraw.

**Moderation under the menu.** On someone else's message, the ⋮ adds *Moderate
the author…* and *Flag the author…* (`mi_chat_moderate_<id>`,
`mi_chat_flag_<id>`), which open the Moderation forms (CSD-065) prefilled with
this room and the author's key: moderation acts on keys, not on messages. They
are unavailable, with "only a moderator of this room", unless the viewer holds
`moderate` here: the node's `viewer_duties` on the transcript when it sends it
(0.5.243), otherwise the `author_duties` on the viewer's own messages. A flag is
recorded and hides nothing yet. *Report to the room's moderators*
(`mi_chat_report_<id>`) is drawn unavailable: no route (CIRISServer#665).

## 3. Contracts (who)

| value | endpoint | owner | state |
Expand All @@ -207,9 +230,14 @@ as a failure, once as a note.
| the contact grant | `GET` / `POST /v1/contacts` | CIRISServer (`src/contacts_chat.rs:3784`) | live — CSD-005 |
| the room's handshake state | carried as a system entry with `message_id: chat.state.*` (`src/contacts_chat.rs:694-751`, `803-818`) | CIRISServer | live — and the client renders it correctly through `SystemNoteRow` + `chatEntryText`, whose fallback rules are id, then the server's English, never a blank line and never the raw key (CIRISClient#34) |
| **does this wait resolve by itself** | `converges_on_its_own` — present on `GET .../messages` (`:3742`) and on the contacts refusal (`:2063`), **absent from the send refusal** (`:2986-2996`) | CIRISServer | **missing on the one route that needs it** |
| edit / withdraw / recant a message | no route — it needs the author's own signature and the app holds no keys | CIRISServer | **missing by design**, and the UI says so per-op rather than hiding the verb |
| where a file in chat is | `GET /v1/files/{id}/custody?cohort&room_id` | CIRISServer — the custody PR, unmerged, unreleased | called — `ui/screens/ChatScreen.kt:397`, as **Where is this file** (`mi_op_where_<id>`) on a message card's `⋮`, only on a row whose `content_type` is not `text/*`. **Dormant**: the chat plane refuses anything but text (`chat.unsupported_content_type`), so no row carries it today. The card is CSD-107's |
| where a file in chat is | `GET /v1/files/{id}/custody?cohort&room_id` | CIRISServer 0.5.218+ (`src/drive.rs`, custody) | called — `ui/screens/ChatScreen.kt:397`, as **Where is this file** (`mi_op_where_<id>`) on a message card's `⋮`, only on a row whose `content_type` is not `text/*`. **Dormant**: the chat plane refuses anything but text (`chat.unsupported_content_type`), so no row carries it today. The card is CSD-107's |
| a CEG family for `chat:message:v1` | `chat:*` (CC 3.1.9 / 3.3.11) | CIRISConstitution | **registered in rc6** (CIRISClient#150) — the body and draft rows bind it |
| the room's files panel: list | `GET /v1/drive?cohort=community&room_id={room}` | CIRISServer | **live** (0.5.242; `room_file` passes in the native harness: 64 KiB and a 3 MiB chunk DAG, bytes identical on the other member's node). `btn_chat_files` opens `chat_room_files_panel`, the Files card (CSD-007) for this room only; `viewer_duties` on this read and on the transcript (0.5.243) says whether the viewer moderates here |
| the panel: add, open, render policy | `POST /v1/files {cohort: community, room_id, …}`, `GET /v1/files/{id}?cohort=community&room_id=…`, `GET /v1/media/policy` | CIRISServer | **live** — the same calls as CSD-007, in this room |
| the panel: rename, move, withdraw a file you sent | `POST /v1/files/{id}/rename {filename}`, `POST /v1/files/{id}/move {cohort, room_id?, keep_source}`, `DELETE /v1/files/{id}?cohort&room_id` | CIRISServer | **live** (0.5.242), author only — CSD-007's acts, one action with two doors |
| (closure only) households and owned nodes | `GET /v1/families`, `GET /v1/setup/owned-nodes` | CIRISServer | **not called in a room**: the Files card reads them only for a family tab; the route checker's closure follows the shared composable |
| a message's moderation items | none here — they open the Moderation forms (CSD-065) for the author in this room | — | moderate and flag act on the AUTHOR's key; drawn unavailable with "only a moderator of this room" for a non-moderator. "Report to the room's moderators" is drawn unavailable: no route (CIRISServer#665) |
| a file shown in the chat as an attachment | send `POST …/messages {body, attachment_attestation_id}`; the transcript's per-message `attachment`; the gate `accepts_attachments: true` on the transcript | CIRISServer 0.5.243 (needs CIRISEdge's unreleased consent fix) | **not offered in this client yet** (planned for client 0.5.238): an older node ignores the field and posts the caption without the file, so Attach is offered only where the transcript says `accepts_attachments: true` |

**Wrong host: none.** Every route here is the NODE's, on `:4243`. The three
calls (`startChat`, `listChatMessages`, `sendChatMessage`) take the node URL
Expand Down
Loading
Loading