Sharing Model
How file sharing works in TMA Cloud.
How file sharing works in TMA Cloud.
Share Links
Overview
Share links provide public access to files and folders without requiring authentication.
Share Link Structure
- Token: Cryptographically secure random token
- Files: One or more files/folders linked
- Expiration: Configurable expiration (
7 days,30 days, ornever). - Owner: User who created the share
Access Control
- Public Access: No authentication required
- Token-Based: Access via unique token
- Read-Only: Share links provide read access only
- Download: Files can be downloaded via share link
- Own items only: A link can only be created for files and folders in the caller's account that are not in Trash. A request that includes any other ID returns 404 Not Found and creates no link
- Trash: An item in Trash is not reachable through a link. Trashing the shared file or folder makes the link return 404 Not Found; trashing an item inside a shared folder removes it from the listing and blocks its download. The link rows are kept, so restoring the item makes it reachable again, until the link expires
Accessing Shared Content
- A shared folder opens a listing page. Files download on click. Subfolders open in place, with a breadcrumb back to the shared root.
- Large public folders load in stable folder-first pages as the visitor scrolls; the page does not use Previous/Next controls.
- A single-file share opens a landing page with the file name, size, and a download button.
- Each folder page has a Download all action that zips the current folder.
- Only items linked to the share are reachable. Browsing a folder that is not part of the share returns 404 Not Found, even with a valid token.
Creating Share Links
Single File Share
Share a single file with a unique link.
Folder Share
Share entire folders, including all contents. The whole subtree is linked to the share, so subfolders are reachable through the same link.
Multiple Files Share
Link multiple files to a single share link.
Adding to a Shared Folder
Items added to a shared folder after it is shared are linked into the same share automatically.
The link is written by the share-linking background queue, not by the upload
request. The request runs one indexed lookup to see whether the parent folder
belongs to a share, and queues the job only if it does. Jobs are keyed per
account, so uploads into the same share are applied in order. A new item can
therefore take a moment to appear on the public link after the upload finishes.
If the queue is unavailable, the link is written inline instead.
Share Link URLs
Default Format
http://your-domain.com/s/{token}Custom Share Domain
Configure a custom share base URL in Settings → Administration → Integrations → Share link address (first user only).
When configured:
http://share.your-domain.com/s/{token}Share domain middleware blocks all routes except /s/*, /health, and /metrics.
Link Expiration
Expiry Options
When creating or re-sharing a link, the user selects one of:
- 7 days (default)
- 30 days
- No expiration
Re-sharing an existing link updates its expiry to the newly selected value.
Expired Link Behavior
- Expired links return 410 Gone on the public page with a "Link expired" message
- The Shared page in the file manager still lists expired files with a red clock icon and "Link expired" label
- Downloads and ZIP exports for expired links are blocked with the same 410 response
Auto-Cleanup
A worker job removes expired share links every Sunday at 06:10 UTC. Cleanup deletes the share_links and share_link_files rows and sets shared = false on files that no longer have an active share link.
Share Management
Viewing Shares
- Go to the Shared section in the file manager
- Active links show the green share icon with a compact countdown in days, hours, or minutes
- Links with no expiration show
∞beside the share icon - Expired links show a red clock icon and "Link expired" label
- Get Info shows when the item was shared, the remaining duration, and the exact expiration time
- Copy share links from the share modal
The shared time is set when an item joins a share. Re-sharing an active item keeps that time. Unsharing clears it, and sharing the item again starts a new time. Descendants of a shared folder and items added to it later receive their own shared time.
Revoking Shares
- Unshare from the context menu or the toolbar
- The link stops working at once
Security Considerations
- Tokens are cryptographically secure
- No authentication required (by design)
- Expiry is checked on every request, not only by the cleanup job
- Redis cache TTL is capped at the link's remaining lifetime to prevent stale access
- Moving an item to Trash clears the cached lookups of every share that contains it, so it stops resolving immediately
- The public lookup requires the link's owner to match the file's owner
- Share domain isolation (optional)
Related Topics
- File System - How files are organized
- User Guide: Share Files - How to create shares
- API: Sharing - API endpoints
Last updated on