Cordy/Cairn

Fork 0

Research Collaborra interation #486

New issue

Closed

opened 2026-09-11 20:11:05 +00:00 by Cordy · 4 comments

Cordy commented

2026-09-11 20:11:05 +00:00

Owner

can we implement this?
what is the benefit?
what would the User/customer gain?
is it free for us to use or is there some license agreements/pitfalls?

can we implement this? what is the benefit? what would the User/customer gain? is it free for us to use or is there some license agreements/pitfalls?

Cordy added this to the v0.7 — Closed beta (dogfood + hardening) milestone

2026-09-11 20:11:05 +00:00

Cordy commented

2026-09-13 14:02:57 +00:00

Author

Owner

Research findings (September 2026), sources at the bottom. Answers in the order the issue asks them, then the competitor comparison, the licensing map, and a proposed design.

1. Can we implement this?

Yes, and the integration surface is small and well-documented. Collabora Online (COOL) integrates through WOPI — a plain HTTP protocol where Cairn acts as the "WOPI host". Per Collabora's own SDK, COOL depends on only three file operations, all of which map directly onto what Cairn already has:

WOPI call	What COOL uses it for	What it maps to in Cairn
`CheckFileInfo` (GET `/wopi/files/<id>`)	name, size, user, permissions	`Store.Stat` + our locks/holds/read-only → `UserCanWrite`
`GetFile` (GET `/wopi/files/<id>/contents`)	download for editing	`Store.Open` through the normal (decrypting) stack
`PutFile` (POST `.../contents`)	save	`Store.Write` — quota, holds and read-only enforcement come free

Plus: fetch /hosting/discovery from the COOL server once (it lists which formats it edits and the iframe URL per format), mint a short-lived access token per user+file (signed HMAC — stateless, no new state file, fits the no-DB architecture), and serve an editor page that embeds the COOL iframe. The web UI side is one "Open in <editor>" entry (kebab + preview panel) behind a boot-probe feature flag, exactly the converter (#297) pattern.

Anything Cairn must get right beyond the minimum: the external-change detection handshake (LastModifiedTime in CheckFileInfo/PutFile + answering 409 with COOLStatusCode: 1010 when X-COOL-WOPI-Timestamp mismatches) — this is what protects against a WebDAV/sync client writing the file mid-editing-session; and bypassing download marking (#423) on WOPI GetFile — a marked file saved back through PutFile would bake the forensic mark into the stored original permanently. Both are handler-level details, not architecture.

2. What is the benefit / what does the user gain?

In-browser editing and real-time co-editing of Writer/Calc/Impress documents (DOCX/XLSX/PPTX and ODF, plus legacy formats) — the single biggest feature gap between Cairn and Nextcloud/OpenCloud/Seafile today. Our preview converter covers viewing legacy formats; this covers editing everything.
Collaborative sessions (multiple cursors, comments, change tracking) with the document never leaving the customer's infrastructure — only rendered screen content reaches the browser, which is precisely Cairn's sovereignty pitch. Works with encryption-at-rest transparently (Cairn decrypts on GetFile like it does for the converter; the COOL hop sits inside the same trust boundary).
For the beta/product story: "sovereign Office in the browser" closes the most common objection when comparing against Nextcloud Office et al.

3. Is it free? Licensing map (as of 2026)

For us (Swiss Cairn): completely free and clean. The WOPI host is our own code; we ship zero Collabora code. Collabora Online is MPL 2.0, fully open source, "inbound == outbound" — integrating against it via HTTP creates no obligations on Cairn's codebase. Their FAQ explicitly frames integration as the point of the product ("implement WOPI support… we have the documentation to help you"). There's a partner programme if we ever want to resell subscriptions — optional, not required.

For the customer, two editions of the same software:

CODE (Collabora Online Development Edition): free, rolling release, no user or feature limits, no SLA/long-term support. Collabora's own framing: Fedora vs RHEL. Fine for dogfood, home, small teams.
Collabora Online (paid subscription, per named user/year): same software with SLA, ~3-year LTS per major version, security maintenance, branding. No per-document or concurrent-session charges; external collaborators free; EDU/NGO discounts.

So the customer decides free-vs-supported; nothing in the integration changes. That's the cleanest licensing story available in this space.

The alternatives, for contrast:

ONLYOFFICE Docs: AGPL v3 open-core. Historically the Community Edition was hard-capped at 20 concurrent connections; version 9.4 (2026) removed that cap and simplified the stack. Still open-core with paid Enterprise (which is where their WOPI/SharePoint knobs and support live), still a much heavier deployment (~4 GB RAM, historically PostgreSQL/RabbitMQ/Redis, being consolidated in 9.4). Better OOXML fidelity than Collabora; weaker ODF. Political wrinkle: in 2026 a European consortium (Nextcloud, IONOS, Proton) forked ONLYOFFICE into "Euro-Office" over transparency/sovereignty concerns, and ONLYOFFICE suspended its Nextcloud partnership. For a Swiss-sovereignty product, hitching to that drama is unattractive; Collabora is the sovereignty-safe bet (and is itself an OpenCloud featured partner).
Microsoft 365 / Office for the web via WOPI: requires membership in Microsoft's Cloud Storage Partner Program — effectively closed to small ISVs. Not a path for us; noted only because oCIS/OpenCloud expose it for customers who have it.

Key architectural fact: all three of the above speak WOPI on the same host-side surface. Build the WOPI host once for Collabora, and ONLYOFFICE (or anything else) becomes a config value later, not a new subsystem.

4. How the competitors implemented it

OpenCloud / oCIS: a dedicated collaboration service (Go) implementing WOPI, plus an app-registry mapping MIME types to registered apps ("Open with…" menu, which is what the #488 reference screenshot showed). Config per app: APP_NAME (display name, admin-chosen), APP_PRODUCT (Collabora/OnlyOffice/Microsoft365 — behavioural quirks per product), APP_ADDR (the document server URL), WOPI_SRC (the externally reachable address of the WOPI endpoints — the document server must be able to call back). Their service is off by default because it needs the external document server. Also relevant: they need a token store (NATS/Redis) for short-token support — Cairn's stateless signed-token approach avoids that dependency entirely.
Nextcloud: the richdocuments app + Collabora ("Nextcloud Office" is white-labelled Collabora), including a "built-in CODE server" appimage for zero-config small installs. The built-in-server trick is not for us (a gigabyte-plus appimage inside a single Go binary is the opposite of our deployment story); our equivalent convenience is Helm/compose packaging of the collabora/code container, like the preview converter.
ownCloud 10 / Seafile: same shape — Collabora via WOPI, ONLYOFFICE via its native API (Seafile ships both connectors).

5. What we have to take into account (pitfalls)

COOL must be reachable by the user's browser (iframe) and must itself reach Cairn's WOPI endpoints. Unlike the Gotenberg converter (internal-only), Collabora needs its own URL + TLS. Deployment docs must cover: reverse proxy, frame-src/frame-ancestors CSP both ways, coolwsd's alias-group allowlist (so the COOL server only serves our WOPI host), and a wopiBase config override for split-horizon DNS.
Access tokens travel in URLs — they must be short-lived, scoped to user+file+permission, and never logged. Signed stateless tokens survive pod restarts (an in-memory store would kill every active editing session on redeploy — with unsaved-save failures).
Download marking (#423) must not apply to WOPI GetFile (mark would round-trip into the stored file). Audit still records open/save; recents (#293) records the open.
Locks/holds/read-only: a file locked by someone else, on hold, or in a read-only space opens read-only (UserCanWrite: false); PutFile re-enforces server-side regardless. COOL handles concurrent editors internally — our lock is for the WebDAV/desktop world, and the timestamp handshake (above) bridges the two.
No versioning in Cairn: autosaves overwrite in place, same as WebDAV PUT. Backend snapshots remain the versioning story (house stance); worth one honest line in the docs.
Trademark/naming: the editor's display name should be admin-configurable (appName, like OpenCloud) and our UI copy generic ("Open in Collabora Online" when that's the configured name). Referential use of the name is fine per their trademark policy.
arm64: collabora/code ships multi-arch — dogfoodable on the Pi cluster, though a small x86 LXC would perform better.

6. Recommended path

Implement a generic WOPI host with Collabora as the first-class target. Config block office.url (+ appName, wopiBase, optional format list), boot-time discovery fetch → feat.office probe → UI entries only when configured — the proven #297 pattern. Phases: (1) backend WOPI host TDD'd against synthetic WOPI calls + token round-trip; (2) editor page + UI entries (mockup first); (3) packaging (Helm optional service, default off, loud docs) + dogfood on the cluster + handbook page. ONLYOFFICE support later = mostly testing + an appProduct switch, if ever needed.

Cairn licence gating — options, decision Nikola's:
(a) available in every licensed tier (drives adoption; customer pays Collabora only if they want the supported edition), or
(b) Business-tier feature (it's a collaboration/enterprise capability, and the enforcement hook exists via feat.lic), or
(c) core open in all tiers, with admin-side controls (per-space edit policy, watermarking) as Business features later.

Sources: Collabora SDK — How to integrate (WOPI) · Collabora FAQ (editions, licensing, MPL, subscriptions) · OpenCloud collaboration service docs · ONLYOFFICE 9.4 removes community connection limit · Collabora vs OnlyOffice after the Euro-Office fork (2026) · oCIS app-registry/app-provider docs

Researched by Claude on behalf of @Cordy.

Research findings (September 2026), sources at the bottom. Answers in the order the issue asks them, then the competitor comparison, the licensing map, and a proposed design. ## 1. Can we implement this? **Yes, and the integration surface is small and well-documented.** Collabora Online (COOL) integrates through **WOPI** — a plain HTTP protocol where Cairn acts as the "WOPI host". Per Collabora's own SDK, COOL depends on only three file operations, all of which map directly onto what Cairn already has: | WOPI call | What COOL uses it for | What it maps to in Cairn | |---|---|---| | `CheckFileInfo` (GET `/wopi/files/<id>`) | name, size, user, permissions | `Store.Stat` + our locks/holds/read-only → `UserCanWrite` | | `GetFile` (GET `/wopi/files/<id>/contents`) | download for editing | `Store.Open` through the normal (decrypting) stack | | `PutFile` (POST `.../contents`) | save | `Store.Write` — quota, holds and read-only enforcement come free | Plus: fetch `/hosting/discovery` from the COOL server once (it lists which formats it edits and the iframe URL per format), mint a short-lived **access token** per user+file (signed HMAC — stateless, no new state file, fits the no-DB architecture), and serve an editor page that embeds the COOL iframe. The web UI side is one "Open in <editor>" entry (kebab + preview panel) behind a boot-probe feature flag, exactly the converter (#297) pattern. Anything Cairn must get right beyond the minimum: the **external-change detection** handshake (`LastModifiedTime` in CheckFileInfo/PutFile + answering 409 with `COOLStatusCode: 1010` when `X-COOL-WOPI-Timestamp` mismatches) — this is what protects against a WebDAV/sync client writing the file mid-editing-session; and **bypassing download marking (#423) on WOPI GetFile** — a marked file saved back through PutFile would bake the forensic mark into the stored original permanently. Both are handler-level details, not architecture. ## 2. What is the benefit / what does the user gain? - **In-browser editing and real-time co-editing** of Writer/Calc/Impress documents (DOCX/XLSX/PPTX and ODF, plus legacy formats) — the single biggest feature gap between Cairn and Nextcloud/OpenCloud/Seafile today. Our preview converter covers *viewing* legacy formats; this covers *editing everything*. - Collaborative sessions (multiple cursors, comments, change tracking) with the document never leaving the customer's infrastructure — only rendered screen content reaches the browser, which is precisely Cairn's sovereignty pitch. Works with encryption-at-rest transparently (Cairn decrypts on GetFile like it does for the converter; the COOL hop sits inside the same trust boundary). - For the beta/product story: "sovereign Office in the browser" closes the most common objection when comparing against Nextcloud Office et al. ## 3. Is it free? Licensing map (as of 2026) **For us (Swiss Cairn): completely free and clean.** The WOPI host is our own code; we ship zero Collabora code. Collabora Online is **MPL 2.0**, fully open source, "inbound == outbound" — integrating against it via HTTP creates no obligations on Cairn's codebase. Their FAQ explicitly frames integration as the point of the product ("implement WOPI support… we have the documentation to help you"). There's a partner programme if we ever want to resell subscriptions — optional, not required. **For the customer, two editions of the same software:** - **CODE** (Collabora Online Development Edition): free, rolling release, **no user or feature limits**, no SLA/long-term support. Collabora's own framing: Fedora vs RHEL. Fine for dogfood, home, small teams. - **Collabora Online** (paid subscription, per named user/year): same software with SLA, ~3-year LTS per major version, security maintenance, branding. No per-document or concurrent-session charges; external collaborators free; EDU/NGO discounts. So the *customer* decides free-vs-supported; nothing in the integration changes. That's the cleanest licensing story available in this space. **The alternatives, for contrast:** - **ONLYOFFICE Docs**: AGPL v3 open-core. Historically the Community Edition was hard-capped at **20 concurrent connections**; version **9.4 (2026) removed that cap** and simplified the stack. Still open-core with paid Enterprise (which is where their WOPI/SharePoint knobs and support live), still a much heavier deployment (~4 GB RAM, historically PostgreSQL/RabbitMQ/Redis, being consolidated in 9.4). Better OOXML fidelity than Collabora; weaker ODF. Political wrinkle: in 2026 a European consortium (Nextcloud, IONOS, Proton) **forked ONLYOFFICE into "Euro-Office"** over transparency/sovereignty concerns, and ONLYOFFICE suspended its Nextcloud partnership. For a Swiss-sovereignty product, hitching to that drama is unattractive; Collabora is the sovereignty-safe bet (and is itself an OpenCloud featured partner). - **Microsoft 365 / Office for the web via WOPI**: requires membership in Microsoft's Cloud Storage Partner Program — effectively closed to small ISVs. Not a path for us; noted only because oCIS/OpenCloud expose it for customers who have it. **Key architectural fact:** all three of the above speak **WOPI on the same host-side surface**. Build the WOPI host once for Collabora, and ONLYOFFICE (or anything else) becomes a config value later, not a new subsystem. ## 4. How the competitors implemented it - **OpenCloud / oCIS**: a dedicated `collaboration` service (Go) implementing WOPI, plus an app-registry mapping MIME types to registered apps ("Open with…" menu, which is what the #488 reference screenshot showed). Config per app: `APP_NAME` (display name, admin-chosen), `APP_PRODUCT` (Collabora/OnlyOffice/Microsoft365 — behavioural quirks per product), `APP_ADDR` (the document server URL), `WOPI_SRC` (the externally reachable address of the WOPI endpoints — the document server must be able to call back). Their service is off by default because it needs the external document server. Also relevant: they need a token store (NATS/Redis) for short-token support — **Cairn's stateless signed-token approach avoids that dependency entirely.** - **Nextcloud**: the `richdocuments` app + Collabora ("Nextcloud Office" is white-labelled Collabora), including a "built-in CODE server" appimage for zero-config small installs. The built-in-server trick is not for us (a gigabyte-plus appimage inside a single Go binary is the opposite of our deployment story); our equivalent convenience is Helm/compose packaging of the `collabora/code` container, like the preview converter. - **ownCloud 10 / Seafile**: same shape — Collabora via WOPI, ONLYOFFICE via its native API (Seafile ships both connectors). ## 5. What we have to take into account (pitfalls) 1. **COOL must be reachable by the user's browser** (iframe) *and* must itself reach Cairn's WOPI endpoints. Unlike the Gotenberg converter (internal-only), Collabora needs its own URL + TLS. Deployment docs must cover: reverse proxy, `frame-src`/`frame-ancestors` CSP both ways, coolwsd's alias-group allowlist (so the COOL server only serves our WOPI host), and a `wopiBase` config override for split-horizon DNS. 2. **Access tokens travel in URLs** — they must be short-lived, scoped to user+file+permission, and never logged. Signed stateless tokens survive pod restarts (an in-memory store would kill every active editing session on redeploy — with unsaved-save failures). 3. **Download marking (#423) must not apply to WOPI GetFile** (mark would round-trip into the stored file). Audit still records open/save; recents (#293) records the open. 4. **Locks/holds/read-only**: a file locked by someone else, on hold, or in a read-only space opens read-only (`UserCanWrite: false`); PutFile re-enforces server-side regardless. COOL handles concurrent editors internally — our lock is for the WebDAV/desktop world, and the timestamp handshake (above) bridges the two. 5. **No versioning in Cairn**: autosaves overwrite in place, same as WebDAV PUT. Backend snapshots remain the versioning story (house stance); worth one honest line in the docs. 6. **Trademark/naming**: the editor's display name should be admin-configurable (`appName`, like OpenCloud) and our UI copy generic ("Open in Collabora Online" when that's the configured name). Referential use of the name is fine per their trademark policy. 7. **arm64**: `collabora/code` ships multi-arch — dogfoodable on the Pi cluster, though a small x86 LXC would perform better. ## 6. Recommended path **Implement a generic WOPI host with Collabora as the first-class target.** Config block `office.url` (+ `appName`, `wopiBase`, optional format list), boot-time discovery fetch → `feat.office` probe → UI entries only when configured — the proven #297 pattern. Phases: (1) backend WOPI host TDD'd against synthetic WOPI calls + token round-trip; (2) editor page + UI entries (mockup first); (3) packaging (Helm optional service, default off, loud docs) + dogfood on the cluster + handbook page. ONLYOFFICE support later = mostly testing + an `appProduct` switch, if ever needed. **Cairn licence gating** — options, decision Nikola's: (a) available in every licensed tier (drives adoption; customer pays Collabora only if they want the supported edition), or (b) Business-tier feature (it's a collaboration/enterprise capability, and the enforcement hook exists via `feat.lic`), or (c) core open in all tiers, with admin-side controls (per-space edit policy, watermarking) as Business features later. --- Sources: [Collabora SDK — How to integrate (WOPI)](https://sdk.collaboraonline.com/docs/How_to_integrate.html) · [Collabora FAQ (editions, licensing, MPL, subscriptions)](https://www.collaboraonline.com/faqs/) · [OpenCloud collaboration service docs](https://docs.opencloud.eu/docs/dev/server/services/collaboration/information/) · [ONLYOFFICE 9.4 removes community connection limit](https://linuxiac.com/onlyoffice-docs-9-4-removes-community-connection-limit/) · [Collabora vs OnlyOffice after the Euro-Office fork (2026)](https://blog.elest.io/collabora-online-vs-onlyoffice-which-self-hosted-office-suite-after-the-euro-office-fork/) · [oCIS app-registry/app-provider docs](https://doc.owncloud.com/ocis/next/deployment/services/s-list/app-registry.html) Researched by Claude on behalf of @Cordy.

Cordy commented

2026-09-13 14:05:15 +00:00

Author

Owner

Decisions (Nikola, 2026-09-13):

Cairn gating: the integration ships in all licensed tiers. Admin-side extras (per-space edit policy, watermarking) may become Business-tier features later.
Scope for v1: open + edit existing files and new-document creation (New → Document / Spreadsheet / Presentation from empty templates, opened straight into the editor).
Timing: research concluded; build deferred — it competes with the remaining v0.7 beta-hardening items. When picked up, the agreed path is: UI mockup first (kebab entry, full-page editor with back navigation, admin Office settings topic) → approval → waves: (1) WOPI host backend TDD (CheckFileInfo/GetFile/PutFile, stateless signed tokens, timestamp/1010 handshake, marks bypass), (2) editor page + UI + new-document flow, (3) Helm/compose packaging (default off) + dogfood CODE on the cluster + handbook.

Issue stays open as the implementation tracker with the research above as the decision record.

Decisions (Nikola, 2026-09-13): - **Cairn gating**: the integration ships in **all licensed tiers**. Admin-side extras (per-space edit policy, watermarking) may become Business-tier features later. - **Scope for v1**: open + edit existing files **and** new-document creation (New → Document / Spreadsheet / Presentation from empty templates, opened straight into the editor). - **Timing**: research concluded; **build deferred** — it competes with the remaining v0.7 beta-hardening items. When picked up, the agreed path is: UI mockup first (kebab entry, full-page editor with back navigation, admin Office settings topic) → approval → waves: (1) WOPI host backend TDD (CheckFileInfo/GetFile/PutFile, stateless signed tokens, timestamp/1010 handshake, marks bypass), (2) editor page + UI + new-document flow, (3) Helm/compose packaging (default off) + dogfood CODE on the cluster + handbook. Issue stays open as the implementation tracker with the research above as the decision record.

Cordy commented

2026-09-13 14:12:17 +00:00

Author

Owner

Deployment + legal posture addendum (2026-09-13):

Dogfood networking plan (Nikola handles DNS):

Public DNS: code.c0rdyceps.ch → A 84.234.21.80 (VPS, standard chain: Caddy → WireGuard → LAN).
LAN: 192.168.10.250 reserved from the MetalLB pool for the Collabora LoadBalancer service (free since the cairn-s3 dogfood retired; .247 remains the spare).
Caddy site block proxies to 192.168.10.250; WebSockets are handled automatically, add a generous body limit. coolwsd gets frame_ancestors = the Cairn origins (files-bao, files), and its alias-group allowlist restricted to our WOPI hosts.

Licensing posture (settled):

The customer deploys the document server themselves; CODE-vs-paid is strictly their relationship with Collabora Productivity Ltd. Cairn ships no Collabora code, binaries or artwork — MPL obligations never attach; the same process/HTTP boundary keeps ONLYOFFICE's AGPL away from us if a customer points the WOPI host there instead.
We observe: referential naming only (no logo shipping, no implied partnership; admin-configurable appName keeps UI copy generic); Helm/compose may reference the public collabora/code image (customer pulls it — same as gotenberg/gotenberg:8 today); if Swiss Cairn ever resells Collabora subscriptions or operates it as a managed service, we join their partner programme first — that is the vehicle for it, and an opportunity rather than a risk.
At feature ship: add one EULA sentence — third-party document servers integrated via WOPI are licensed separately by their vendors; Swiss Cairn grants no rights to them — and have the lawyer glance at it with the next EULA pass.

Deployment + legal posture addendum (2026-09-13): **Dogfood networking plan** (Nikola handles DNS): - Public DNS: `code.c0rdyceps.ch` → A `84.234.21.80` (VPS, standard chain: Caddy → WireGuard → LAN). - LAN: **192.168.10.250 reserved** from the MetalLB pool for the Collabora LoadBalancer service (free since the cairn-s3 dogfood retired; .247 remains the spare). - Caddy site block proxies to 192.168.10.250; WebSockets are handled automatically, add a generous body limit. coolwsd gets `frame_ancestors` = the Cairn origins (files-bao, files), and its alias-group allowlist restricted to our WOPI hosts. **Licensing posture (settled):** - The customer deploys the document server themselves; CODE-vs-paid is strictly their relationship with Collabora Productivity Ltd. Cairn ships no Collabora code, binaries or artwork — MPL obligations never attach; the same process/HTTP boundary keeps ONLYOFFICE's AGPL away from us if a customer points the WOPI host there instead. - We observe: referential naming only (no logo shipping, no implied partnership; admin-configurable `appName` keeps UI copy generic); Helm/compose may *reference* the public `collabora/code` image (customer pulls it — same as `gotenberg/gotenberg:8` today); if Swiss Cairn ever resells Collabora subscriptions or operates it as a managed service, we join their partner programme first — that is the vehicle for it, and an opportunity rather than a risk. - At feature ship: add one EULA sentence — third-party document servers integrated via WOPI are licensed separately by their vendors; Swiss Cairn grants no rights to them — and have the lawyer glance at it with the next EULA pass.

Cordy referenced this issue from a commit

2026-09-13 15:18:32 +00:00

scout: locate anchors for #486 WOPI/office build

Cordy referenced this issue from a commit

2026-09-13 15:29:50 +00:00

one-shot: #486 WOPI office integration — failing tests first (red)

forgejo-actions referenced this issue from a commit

2026-09-13 15:32:46 +00:00

test(#486): WOPI office integration — witnessed-red suite

Cordy referenced this issue from a commit

2026-09-13 16:22:55 +00:00

one-shot: #486 WOPI office integration — implementation (green)

Cordy referenced this issue from a commit

2026-09-13 16:29:40 +00:00

one-shot: commit verified #486 backend from persisted workspace

Cordy referenced this issue from a commit

2026-09-13 16:31:24 +00:00

scout3: frontend regions for #486 wave 2

Cordy referenced this issue from a commit

2026-09-13 16:35:34 +00:00

scout4: admin rail + slots + overview row helper for #486 card

forgejo-actions referenced this issue from a commit

2026-09-13 16:38:03 +00:00

feat(#486): WOPI host + Collabora Online integration backend

forgejo-actions referenced this issue from a commit

2026-09-13 16:38:03 +00:00

chore(#486): remove one-shot scaffolding workflows

Cordy referenced this issue from a commit

2026-09-13 16:42:23 +00:00

one-shot: #486 wave 2 — office editing UI per mockup rev 2

forgejo-actions referenced this issue from a commit

2026-09-13 16:45:18 +00:00

feat(#486): office editing UI per mockup rev 2

Cordy referenced this issue from a commit

2026-09-13 16:47:44 +00:00

one-shot: #486 wave 3 — docs, EULA, packaging notes, changelog, wopiBase env

forgejo-actions referenced this issue from a commit

2026-09-13 16:49:34 +00:00

docs+packaging(#486): handbook page, EULA clause, compose/chart notes, changelog; CAIRN_OFFICE_WOPI_BASE env

Cordy referenced this issue

2026-09-13 16:49:55 +00:00

#486: in-browser document editing via WOPI (Collabora Online integration) #516

Cordy referenced this issue from a commit

2026-09-13 16:51:04 +00:00

Merge pull request '#486: in-browser document editing via WOPI (Collabora Online integration)' (#516) from fix-486 into main

Cordy commented

2026-09-13 16:54:53 +00:00

Author

Owner

Shipped in v0.6.178 (PR #516), live on both dogfoods. Built exactly to the approved office-editor mockup rev 2.

Deployed infrastructure

Collabora CODE 26.04.3.2.1 (multi-arch, arm64 on pi5) in homelab-config k3s/collabora/: MetalLB 192.168.10.250, Service 80→9980, ssl.enable=false + ssl.termination=true behind your Caddy route, aliasgroups for files.c0rdyceps.ch / files-bao.c0rdyceps.ch / 192.168.10.249 (these also feed coolwsd's frame-ancestors, so the iframe is permitted). Discovery verified end-to-end through code.c0rdyceps.ch: 74 edit actions, all six target formats.

Backend (witnessed-red TDD, internal/office + internal/api)

Discovery client: edit actions only, 10-minute cache, last error kept for the admin card. Formats are never hardcoded.
Stateless HMAC access tokens, keyed per boot: a token pins user + path + write-bit + expiry, so a leaked token reaches nothing else and a restart ends editor sessions (same lifetime as browser sessions). Tokens never land in logs — the request log records the path without the query.
/wopi/files/{id} (+/contents) mounted on the OUTER mux beside /login and /s/: CheckFileInfo (UserCanNotWriteRelative — no Save As), GetFile, PutFile. The verified token's user is injected into the request context, so the scoped storage stack resolves paths, per-user encryption keys, quota, holds, locks and read-only spaces exactly as for that user's own session.
The two safety-critical details from the research both landed: PutFile does the X-COOL-WOPI-Timestamp handshake (mismatch → 409 + COOLStatusCode: 1010, so external WebDAV/sync changes become an overwrite-or-reload prompt instead of a silent clobber), and GetFile runs under marks.ContextSkipMarking so an edit round-trip can never bake a #423 download mark into the stored file.
/api/v1/office/open decides write access up front (read-only space / covering lock with owner / legal hold) and states the reason; Recents + office-open audit on open. POST /api/v1/files/new creates from templates embedded in the binary (minimal ODF and OOXML built at release; md/txt empty) through the scoped store.
Config office{url, appName, wopiBase}; env CAIRN_OFFICE_URL / CAIRN_OFFICE_WOPI_BASE win, which is how the dogfoods are configured (GitOps env, config Secrets untouched).

Frontend (mockup rev 2, all four variants)

Row menu: "Edit in Collabora Online" directly under Open, pencil glyph from the mockup; preview header gains the accent Edit button.
New ▾ menu: Folder · Document/Spreadsheet/Presentation (.odt/.ods/.odp) · Word/Excel/PowerPoint (.docx/.xlsx/.pptx) · Markdown/Text, extension chips as accent pills; office entries only when configured, md/txt always; name dialog with extension pre-filled; documents open straight into the editor.
Editor page: full-viewport takeover, single 40px bar (← Back, centred name+path, amber read-only chip naming the exact reason, app tag), token by form POST into the iframe, browser back and ← both return, deliberately no Save button.
Administration → Document editor: new Instance-rail topic with the read-only kvbox card (green connected + format count / amber not configured / amber unreachable with the fetch error verbatim; Server, App name, New documents, format chips + "+n more", config.json/env kvfoot). i18n ×4 throughout.

Docs/legal: handbook document-editing.md (+ index row), EULA "Third-party document servers" clause with the agreed wording, compose + chart notes (default off, browser-facing warning), CHANGELOG v0.6.178.

Live verification: both dogfoods report office editor enabled endpoint=https://code.c0rdyceps.ch app="Collabora Online" at v0.6.178; /wopi/files/* answers 401 on a bad token through the public route (the exact path COOL calls); office probe correctly session-gated.

The one check only a signed-in human can do: open a docx on files-bao, watch it render in the editor, type, and confirm the save round-trip. That's yours, champ.

Shipped in **v0.6.178** (PR #516), live on both dogfoods. Built exactly to the approved office-editor mockup rev 2. **Deployed infrastructure** - Collabora CODE 26.04.3.2.1 (multi-arch, arm64 on pi5) in homelab-config `k3s/collabora/`: MetalLB 192.168.10.250, Service 80→9980, `ssl.enable=false` + `ssl.termination=true` behind your Caddy route, aliasgroups for files.c0rdyceps.ch / files-bao.c0rdyceps.ch / 192.168.10.249 (these also feed coolwsd's frame-ancestors, so the iframe is permitted). Discovery verified end-to-end through code.c0rdyceps.ch: 74 edit actions, all six target formats. **Backend (witnessed-red TDD, `internal/office` + `internal/api`)** - Discovery client: edit actions only, 10-minute cache, last error kept for the admin card. Formats are never hardcoded. - Stateless HMAC access tokens, keyed per boot: a token pins user + path + write-bit + expiry, so a leaked token reaches nothing else and a restart ends editor sessions (same lifetime as browser sessions). Tokens never land in logs — the request log records the path without the query. - `/wopi/files/{id}` (+`/contents`) mounted on the OUTER mux beside /login and /s/: CheckFileInfo (`UserCanNotWriteRelative` — no Save As), GetFile, PutFile. The verified token's user is injected into the request context, so the scoped storage stack resolves paths, per-user encryption keys, quota, holds, locks and read-only spaces exactly as for that user's own session. - The two safety-critical details from the research both landed: PutFile does the `X-COOL-WOPI-Timestamp` handshake (mismatch → 409 + `COOLStatusCode: 1010`, so external WebDAV/sync changes become an overwrite-or-reload prompt instead of a silent clobber), and GetFile runs under `marks.ContextSkipMarking` so an edit round-trip can never bake a #423 download mark into the stored file. - `/api/v1/office/open` decides write access up front (read-only space / covering lock with owner / legal hold) and states the reason; Recents + `office-open` audit on open. `POST /api/v1/files/new` creates from templates embedded in the binary (minimal ODF and OOXML built at release; md/txt empty) through the scoped store. - Config `office{url, appName, wopiBase}`; env `CAIRN_OFFICE_URL` / `CAIRN_OFFICE_WOPI_BASE` win, which is how the dogfoods are configured (GitOps env, config Secrets untouched). **Frontend (mockup rev 2, all four variants)** - Row menu: "Edit in Collabora Online" directly under Open, pencil glyph from the mockup; preview header gains the accent Edit button. - New ▾ menu: Folder · Document/Spreadsheet/Presentation (.odt/.ods/.odp) · Word/Excel/PowerPoint (.docx/.xlsx/.pptx) · Markdown/Text, extension chips as accent pills; office entries only when configured, md/txt always; name dialog with extension pre-filled; documents open straight into the editor. - Editor page: full-viewport takeover, single 40px bar (← Back, centred name+path, amber read-only chip naming the exact reason, app tag), token by form POST into the iframe, browser back and ← both return, deliberately no Save button. - Administration → Document editor: new Instance-rail topic with the read-only kvbox card (green connected + format count / amber not configured / amber unreachable with the fetch error verbatim; Server, App name, New documents, format chips + "+n more", config.json/env kvfoot). i18n ×4 throughout. **Docs/legal**: handbook `document-editing.md` (+ index row), EULA "Third-party document servers" clause with the agreed wording, compose + chart notes (default off, browser-facing warning), CHANGELOG v0.6.178. **Live verification**: both dogfoods report `office editor enabled endpoint=https://code.c0rdyceps.ch app="Collabora Online"` at v0.6.178; `/wopi/files/*` answers 401 on a bad token through the public route (the exact path COOL calls); office probe correctly session-gated. The one check only a signed-in human can do: open a docx on files-bao, watch it render in the editor, type, and confirm the save round-trip. That's yours, champ.

Cordy closed this issue

2026-09-13 16:55:03 +00:00

Cordy referenced this issue

2026-09-13 17:05:19 +00:00

Docs alignment run for v0.6.170–178 #517

Cordy referenced this issue

2026-09-13 17:51:15 +00:00

Mobile / phone experience pass for the web UI #389