Feature Specification: External Sharing

1. Overview & Vision

External Sharing enables secure collaboration with individuals outside the organization. It allows users to generate temporary, tokenized links to files, providing a safe alternative to email attachments while maintaining central control and auditability over shared assets.

2. Personas & Stakeholders

Persona	Goal
User	Share project deliverables with clients or partners.
External Recipient	Securely download shared files without an account.
Admin	Monitor and revoke external access links across the org.

3. User Stories

• As a user, I want to share a PDF link that expires in 3 days so the client can review the proposal.
• As a user, I want to revoke a link immediately if I shared the wrong version.
• As a recipient, I want to download the file directly from the link without logging in.

4. Functional Requirements (FR)

• REQ-SH-001: Generate unique, non-guessable sharing tokens (base64url random bytes).
• REQ-SH-002: Configurable link expiry: exactly 1, 3, or 7 days (ttlDays).
• REQ-SH-003: Manual revocation of active sharing links (soft-delete via revokedAt).
• REQ-SH-004: Password protection for shared links (planned for v1.2).

5. Non-Functional Requirements (NFR)

• Security: Tokens MUST be cryptographically secure (UUID v4 or similar).
• Latency: Share link generation < 100ms.

6. Business Logic & Rules

• Token Format: drive.venizia.ai/s/{token}.
• Expiry Logic: Links become invalid instantly once the expires_at timestamp is passed.
• Access Log: Every download via a share link is recorded (planned).

7. User Interface (UI/UX)

• "Share" modal with expiry selection and "Copy Link" button.
• "Shared Links" management tab showing active links and their status.
• Public Landing Page for recipients with file metadata and download button.

8. Information Architecture

• Context menu action on any file.
• Central "External Shares" view in Drive settings.

9. Data Model & Persistence

• Table: share_links.
• Fields: fileId, token, expiresAt, createdBy, revokedAt.

10. API & Service Layer

• POST /api/files/:id/share — create share link ({ ttlDays: 1 | 3 | 7 })
• GET /api/files/:id/share — list active share links for a file
• DELETE /api/files/:id/share/:linkId — revoke a share link
• GET /api/public/files/:token — public download (no auth required)

11. Integration Patterns

• Direct Streaming: The public share handler verifies the token (expiry + revocation check), then streams the file binary directly from MinIO to the HTTP response. No presigned URL is generated.

12. Security & Permissions

• RBAC: drive:share required to generate links.
• Public Access: Shared links bypass Shell SSO but are strictly limited to the specific file metadata and binary content.

13. Error Handling & Resilience

• Invalid Token: Friendly "This link is no longer available" landing page.
• File Deleted: Shared links are automatically invalidated if the source file is deleted.

14. Performance & Scalability

• Token lookups are indexed for high-concurrency public access.

15. Globalization & i18n

• Public sharing page available in English and Vietnamese.

16. Accessibility (a11y)

• Public landing page follows WCAG 2.2 for easy downloading on mobile/desktop.

17. Observability & Analytics

• Tracking of "External Downloads" to identify high-traffic shared assets.

18. Testing & Quality

• Integration tests for token expiration.
• Security audit of the public endpoint to prevent parameter tampering.

19. Constraints & Assumptions

• Assumes recipients have a standard web browser to access the link.

20. Future Enhancements

• View-only (No download) mode using an in-browser PDF viewer.
• "Shared with me" internal list for cross-org collaboration (v2).