Fileshare Token

Overview

The FSHR (Fileshare) token represents sharing a file with another user. It grants the recipient access to view or edit the specified file. Like every action token it is content-addressed — see Content Addressing.

Token Structure

Field Type Required Description
iss identity Yes The identity sharing the file
aud identity Yes The recipient of the share
iat timestamp Yes Issue time
k string Yes Signing key ID
t string Yes Type with optional subtype: FSHR, FSHR:COMMENT, FSHR:WRITE, FSHR:DEL
sub string Yes File ID being shared (e.g., f1~abc123)
c object Yes Share content (see below)

Subtypes

Type String Granted access Description
FSHR read (R) View-only access (default)
FSHR:COMMENT comment (C) View and comment
FSHR:WRITE write (W) Edit access (also used for admin shares)
FSHR:DEL — Revokes a previous share

Content Schema

Field Type Required Description
contentType string Yes MIME type (e.g., application/pdf)
fileName string Yes Original filename
fileTp string Yes File type: BLOB, CRDT, or RTDB

File Types

Type Description
BLOB Static binary file (images, PDFs, etc.)
CRDT Collaborative document (real-time editing)
RTDB Real-time database document

Database Key

The database key for a fileshare token is [t, sub, aud] — type, the file being shared and the recipient, so only one active fileshare exists per (file, recipient) pair. See Database Keys.

Example:

  • Alice shares file with Bob → Stored with key ["FSHR", f1~file123, bob.example.com]
  • Alice updates the share → New token with same key, previous one is marked deleted
  • Only ONE active fileshare of the same file to the same recipient

Examples

Read-Only Share

User @alice.cloudillo.net shares a PDF with @bob.cloudillo.net (read-only):

Field Value
iss alice.cloudillo.net
aud bob.cloudillo.net
iat 2024-04-13T00:01:10.000Z
k 20240101
t FSHR
sub f1~7NtuTab_K4FwYmARMNuk4
c.contentType application/pdf
c.fileName report.pdf
c.fileTp BLOB

Write Access Share

User @alice.cloudillo.net grants edit access to a collaborative document:

Field Value
iss alice.cloudillo.net
aud bob.cloudillo.net
iat 2024-04-13T00:01:10.000Z
k 20240101
t FSHR:WRITE
sub f1~collaborative_doc_id
c.contentType application/vnd.cloudillo.doc
c.fileName Team Notes.quillo
c.fileTp CRDT

Revoke Share

User @alice.cloudillo.net revokes Bob’s access:

Field Value
iss alice.cloudillo.net
aud bob.cloudillo.net
iat 2024-04-13T00:05:00.000Z
k 20240101
t FSHR:DEL
sub f1~7NtuTab_K4FwYmARMNuk4

Integration with References

File shares can be combined with references for public sharing:

  1. Create FSHR action to share with specific user
  2. Or create a reference with type: share.file for public/guest access
  3. Reference tokens support accessLevel: read or accessLevel: write

Access Control Flow

A non-DEL share requires the recipient to accept it. On receipt the action rests at status C (confirmation required); only on acceptance does the recipient’s server create the shared file entry and cache the access level. FSHR:DEL is processed without confirmation.

Owner creates FSHR action
  ↓
Action sent to recipient via federation
  ↓
Recipient's server verifies JWT signature and audience
  ↓
Status set to 'C' (confirmation required)
  ↓
Recipient accepts → file entry created, access granted:
  - FSHR         → read
  - FSHR:COMMENT → comment
  - FSHR:WRITE   → write
  ↓
Access revoked on FSHR:DEL receipt

See Also