diff --git a/024-file-tokens.md b/024-file-tokens.md new file mode 100644 index 0000000..bea833e --- /dev/null +++ b/024-file-tokens.md @@ -0,0 +1,204 @@ +# File tokens + +- Implementation Owner: @lohanidamodar +- Start Date: 20-06-2023 +- Target Date: N/A +- Appwrite Issue: + [Is this RFC inspired by an issue in appwrite](https://github.com/appwrite/appwrite/issues/) + +## Summary + +[summary]: #summary + + + +Accessing files currently requires either files to be public or need user session with user that have access permission. It's mainly painful for image previews that we want to show publicly. For this reason, we want to introduce file tokens. The tokens will be linked to specific file and will be passed in URL for previews and downloads to provide access. + +## Problem Statement (Step 1) + +[problem-statement]: #problem-statement + +**What problem are you trying to solve?** + + + +Currently only way to access private files in Appwrite storage is by using a user session. However it's painful for image previews that we want to display on our applications. Also there are no safe ways to share file with external users or applications without making is completely public. + +That is why we want to introduce file tokens. A file toke will be linked to files and manage it's own permissions over the resource as what kind of access the token will have to the file. Token can be passed as a header or request get parameter. + +## Design proposal (Step 2) + +[design-proposal]: #design-proposal + + + +### API Endpoints + + + +Tokens will be a part of storage service + +**POST /v1/storage/buckets/:bucketId/files/:fileId/tokens** - create token +**PUT /v1/storage/buckets/:bucketId/files/:fileId/tokens** - update token +**GET /v1/storage/buckets/:bucketId/files/:fileId/tokens** - List token +**GET /v1/storage/buckets/:bucketId/files/:fileId/tokens/:tokenId** - Get token +**DELETE /v1/storage/buckets/:bucketId/files/:fileId/tokens/:tokenId** - delete token + + +### Data Structure + + + +We need to introduce new collection to save tokens. + +**resource_tokens** + - resourceId - String + - resourceInternalId - String + - resourceType = String + - secret - String + - expiryDate - date time + +> Note: Resource ID / InternalId will need a structure to incorporate the parent resource as well. For example when resource is file we need both bucketId and fileId. We can use `:` as a separator to keep the resource Id in single field. So for the tokens for file the resource Id will be `bucketId:fileId` and similarly for a document it will be `databaseId:collectionId:documentId` + +We will also need a token validator, that will validate that the token is not expired and has access to the resources. + +### New Resource + +We will add a `token` resource to App, that will get token from request, validate it and return the details if valid. The returned details will contain the actual details of the resource based on resourceId and type breakdown. + +### Supporting Libraries + + + +We will be using JWT to create token that has the payload `tokenId`, `resourceId`, `resourceType` and `expiryDate` + +### Breaking Changes + + + +This shouldn't break any existing features + +### Reliability (Tests & Benchmarks) + +#### Scaling + + +This will be part of Appwrite core, which should scale along with the existing Appwrite infrastructure. + +#### Benchmarks + + + +We don't need separate banchmark as this is part of Appwrite core API + +#### Tests (UI, Unit, E2E) + + + +We will write relevant Unit and E2E test for this feature. + +### Documentation & Content + + + +We need to update storage documentation. Specially on the file preview, view and downloads. + +* It might be a good idea to create a separate guide, file tokens that provides guide on previewing, viewing and downloading files using the tokens + +### Prior art + +[prior-art]: #prior-art + + + +- File tokens are used by many similar services to provide file access. + +### Unresolved questions + +[unresolved-questions]: #unresolved-questions + + + + + +1. Token permission (read, write, update, delete), right now we only provide read permission + +### Future possibilities + +[future-possibilities]: #future-possibilities + + + + + +* Use token for other resources +* More granular permission control to allow read/create/update/delete permissions to make something like google docs possible