Skip to content

feat: add intent parameter to distinguish file preview from download#2281

Open
yuuhikaze wants to merge 1 commit intoopencloud-eu:mainfrom
yuuhikaze:feat/file-intent-distinction
Open

feat: add intent parameter to distinguish file preview from download#2281
yuuhikaze wants to merge 1 commit intoopencloud-eu:mainfrom
yuuhikaze:feat/file-intent-distinction

Conversation

@yuuhikaze
Copy link
Copy Markdown

@yuuhikaze yuuhikaze commented Apr 2, 2026

Summary

Add client-side intent signaling to distinguish between file previews and downloads for audit logging. This enables fine-grained access control policies (e.g., ban downloads of MP4/PDF while allowing previews).

Purpose

Enable OpenCloud to audit and control file access patterns by distinguishing:

  • View: User opens file in browser/app for reading
  • Download: User saves file locally

This allows organizations to implement policies like:

  • Allow viewing of MP4 videos but ban downloads
  • Allow previews of PDFs but track/restrict downloads
  • Enforce different rules based on file type and user group

Microsoft 365 implements similar intent signaling, making this a standard pattern for collaborative platforms.

Changes

  • Intent Parameter Support: Added intent parameter ('preview'|'download') to getFileUrl()
  • Viewer Apps Updated: All file viewers now explicitly signal intent:
    • Preview app (images, videos, audio)
    • PDF viewer
    • EPUB reader
    • Text editor
  • Download Signaling: Download composable explicitly passes intent: 'download'
  • Query Parameter & Headers: Intent propagates via:
    • Query parameter: ?intent=preview|download
    • HTTP header: X-OC-Intent
  • Preview Service: Thumbnail generation includes intent: 'preview'

Testing Status

⚠️ Proof of Concept: Changes have not been fully tested. This PR is a reference implementation and requires:

Notes

  • Backward compatible: defaults to 'download' intent if not specified
  • No changes to existing API contracts
  • Purely additive - existing code paths unchanged

- Add 'intent' parameter support to getFileUrl() with 'preview' or 'download' values
- Update all viewer apps to pass intent: 'preview':
  - Preview app (images, videos, audio)
  - PDF viewer
  - EPUB reader
  - Text editor
- Add intent: 'download' to download composable
- Include intent in preview service thumbnail URLs
- Modify addIntentToUrl() to append intent as query parameter
- Pass X-OC-Intent header for inline file access

This enables the audit service to distinguish between file views and downloads
for compliance tracking, with intent metadata propagating through HTTP headers
and query parameters to the backend services.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant