[ZanardiZZ]

Summary

Draft contract and implementation plan for the NextExplorer side of the OpenWebUI -> ONLYOFFICE handoff.

Why this is a Draft PR

The deployed environment contains exploratory changes for import, /browse preview, ONLYOFFICE callbacks, and persistent associations. The changes need to be reconstructed cleanly in the repository and completed with authenticated end-to-end tests.

Proposed behavior

• Accept a short-lived authenticated handoff from OpenWebUI.
• Import only on first association; reuse the canonical Explorer document afterward.
• Preserve logical names and deterministic _v1, _v2, _v3 versions.
• Open Office formats through /browse and previewManager.
• Save ONLYOFFICE callbacks to the associated canonical document.
• Keep storage roots, allowed origins, callback settings, and secrets configurable.
• Never expose secrets, cookies, JWTs, signed URLs, or internal paths.

Scope planned for this PR

• Handoff request/response contract.
• OpenWebUI origin and expiry validation.
• Persistent association storage.
• Duplicate-import prevention.
• ONLYOFFICE callback continuity.
• Configuration and deployment documentation.
• Backend/frontend tests for authorization, expiry, replay, callbacks, and versioning.

Explicit non-goals

• Replacing NextExplorer authentication.
• Publishing public editor links without a sharing policy.
• Guessing a document from the newest file in a directory.

Validation status

• Initial integration contract documented.
• Configuration implementation completed.
• Handoff implementation extracted from the live deployment.
• Callback and association tests added.
• Frontend browse/preview tests added.
• Authenticated OpenWebUI -> NextExplorer -> ONLYOFFICE test passed.
• Reopen uses the existing association without duplicate import.

See docs/integrations/openwebui-onlyoffice-handoff.md for the evolving contract.