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	`FSHR` or `FSHR:WRITE` or `FSHR:DEL`
`sub`	string	Yes	File ID being shared (e.g., `f1~abc123`)
`c`	object	Yes	Share content (see below)

Subtypes

Subtype	Type String	Description
Read (default)	`FSHR`	View-only access to the file
Write	`FSHR:WRITE`	Edit access to the file
Delete	`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:

The entire JWT token (header + payload + signature) is hashed
Action ID format: a1~{base64_hash}
See Content-Addressing & Merkle Trees for details

Database Key

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

Purpose: This key ensures that a user can only have one active fileshare for a given file. The key components are:

iss: Issuer identity (who is sharing)
t: Token type (FSHR)
sub: Subject (the file being shared)

Example:

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

Examples

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

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

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:

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

Access Control Flow

Owner creates FSHR action
  ↓
Action sent to recipient via federation
  ↓
Recipient's server verifies:
  - JWT signature
  - Issuer owns the file
  - Recipient matches audience
  ↓
Access granted based on subtype:
  - FSHR → Read access
  - FSHR:WRITE → Write access
  ↓
Access revoked on FSHR:DEL receipt