Add Proper Implementation for Uppy Companion

[andrewbrazzatti]

Summary

This issue tracks the implementation of a production-ready Uppy Companion integration for the FileUploadComponent introduced in PR #3693.

PR #3693 added frontend support for Uppy with TUS-based resumable uploads and optional cloud providers such as Dropbox, Google Drive, and OneDrive. While Companion support and configuration scaffolding were introduced, the current implementation is primarily suitable for development and integration testing.

This issue focuses on delivering a fully supported, secure, and configurable Companion implementation suitable for production deployments.

---

Background

PR: #3693

The PR delivered:

• FileUploadComponent integrated into the Angular form module
• Uppy integration including:
  • @uppy/core
  • @uppy/dashboard
  • Provider plugins (Dropbox, Google Drive, OneDrive)
  • @uppy/tus
• Initial Companion support and configuration wiring
• Backend type extensions for Companion configuration
• Enhanced form save event handling for attachment rebinding
• Unit test coverage for the component
• Integration test environment support for Companion flows

At present, Companion support exists but does not yet provide a hardened, configurable, production-grade implementation.

---

Problem Statement

Uppy Companion acts as a proxy server enabling:

• OAuth flows for cloud providers
• Secure token exchange
• File import from third-party services
• Streaming uploads to TUS endpoints

A proper implementation must address:

• Secure credential management
• Environment-specific configuration
• OAuth callback handling
• Multi-tenant considerations
• Deployment topology (reverse proxy, base URL handling)
• Logging and error handling
• Optional provider enablement

Without a hardened implementation:

• Production deployments may be insecure or incomplete
• OAuth flows may fail under reverse proxy or SaaS configurations
• Provider configuration may be inconsistent across environments
• Multi-tenant isolation may be unclear

---

Objectives

• Provide a production-ready Companion server configuration
• Ensure secure handling of provider credentials and OAuth flows
• Support multi-environment and SaaS deployments
• Integrate cleanly with existing attachment storage (file and S3)
• Maintain type safety and configuration validation

---

Proposed Scope

1. Companion Server Configuration

• Define a clear configuration structure for:

  • Enabled providers
  • OAuth credentials
  • Base URLs and callback URLs
  • Allowed origins
  • Upload targets

• Add bootstrap validation to:

  • Ensure required provider credentials are present
  • Fail early if Companion is enabled but misconfigured

• Support environment-specific configuration (e.g. dev vs prod)

2. OAuth and Security Hardening

• Ensure correct OAuth redirect URI handling
• Support reverse proxy and base path deployments
• Restrict allowed origins appropriately
• Review CSRF and token handling alignment with existing security model
• Validate session and cookie handling strategy

3. Multi-Tenant and SaaS Considerations

• Clarify whether Companion runs:
  • Per tenant
  • Shared across tenants
• Ensure no cross-tenant data leakage
• Validate storage routing when S3-backed attachments are used

4. Deployment Model

• Document recommended deployment topology:
  • Same Node process
  • Separate service
  • Behind reverse proxy
• Ensure compatibility with Docker-based deployments
• Validate base URL and location header normalization

5. Logging and Observability

• Add structured logging for:
  • Provider authentication events
  • Upload failures
  • OAuth errors
• Ensure logs integrate with existing platform logging

6. Testing

• Extend integration tests to:
  • Simulate provider-enabled configuration
  • Validate Companion-enabled upload flows
• Add negative tests for misconfiguration scenarios
• Ensure CI does not depend on real cloud provider credentials

---

Acceptance Criteria

• Companion can be enabled via configuration in a production-ready manner
• Provider credentials are validated at bootstrap
• OAuth flows function correctly under reverse proxy deployments
• Multi-tenant behaviour is clearly defined and safe
• Integration tests cover Companion-enabled flows
• CI builds and tests pass
• Documentation describes configuration and deployment requirements

---

Out of Scope

• Adding new cloud providers beyond Dropbox, Google Drive, and OneDrive
• Introducing new attachment storage backends
• UI changes unrelated to Companion enablement

---

Notes

This work is essential to move Companion from development-ready scaffolding to a fully supported production capability.

The implementation should align with:

• Recent attachment storage refactors
• S3-backed deployments
• Multi-tenant SaaS strategy
• Strong configuration validation patterns already introduced in bootstrap logic

Care should be taken to avoid introducing insecure defaults while preserving backward compatibility where feasible.