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.

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

Content-Addressing

This token is content-addressed using SHA-256:

Database Key

The database key for a fileshare token is [t, sub, aud]

Purpose: This key ensures that only one active fileshare exists per (file, recipient) pair. The key components are:

  • t: Token type (FSHR)
  • sub: Subject (the file being shared)
  • aud: Audience (the recipient)

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