From a671df29aa3b36fcd264841632fadae12d6cdfdd Mon Sep 17 00:00:00 2001
From: Damodar Lohani <dlohani48@gmail.com>
Date: Tue, 20 Jun 2023 05:34:06 +0000
Subject: [PATCH 1/6] RFC basic information

---
 024-file-tokens.md | 184 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 184 insertions(+)
 create mode 100644 024-file-tokens.md

diff --git a/024-file-tokens.md b/024-file-tokens.md
new file mode 100644
index 0000000..1f6d095
--- /dev/null
+++ b/024-file-tokens.md
@@ -0,0 +1,184 @@
+# 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
+
+<!-- Brief explanation of the proposed contribution. Write your answer below. -->
+
+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?**
+
+<!--
+What problem are you trying to solve? Explain the context or background in which this problem exists.
+Please avoid discussing your proposed solution.
+-->
+
+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.
+
+## Design proposal (Step 2)
+
+[design-proposal]: #design-proposal
+
+<!--
+This is the technical portion of the RFC. Explain the design in sufficient detail, keeping in mind the following:
+
+- Its interaction with other parts of the system is clear
+- It is reasonably clear how the contribution would be implemented
+- Dependencies on libraries, tools, projects, or work that isn't yet complete
+- New API routes that need to be created or modifications to the existing routes (if needed)
+- Any breaking changes and ways in which we can ensure backward compatibility.
+- Use Cases
+- Goals
+- Deliverables
+- Changes to documentation
+- Ways to scale the solution
+
+Ensure that you include examples and code snippets to allow the community to understand the proposed solution. **It would be best if the examples use naming conventions that you intend to use during the actual implementation to suggest changes early on during the development.**
+
+Write your answer below.
+
+-->
+
+### API Endpoints
+
+<!--
+List the new API routes or endpoints that we might need to add for supporting the new feature.
+Keep in mind to stay very strict to the API protocol and method, whether your new
+changes are for the REST, WebSocket or any other API protocol Appwrite supports.
+
+For example:
+
+**POST /v1/coffee ** - an endpoint for creating coffee.
+**DELETE /v1/coffee ** - an endpoint for deleting coffee.
+-->
+
+We will introduce a new `Tokens` service, that will allow us to manage tokens.
+
+**POST /v1/tokens** -           create token
+**PUT /v1/tokens** -            update token
+**GET /v1/tokens** -            List token
+**GET /v1/tokens/:tokenId** -   Get token
+**DELETE /v1/tokens** -         delete token
+
+
+### Data Structure
+
+<!--
+What kind of changes or additions are required for the Appwrite base collections
+to support this feature. Explain which entities should be added or updated, what new attributes they
+need to have and why. Please think well about the naming conventions and how well they play with other
+Appwrite conventions. Try and stay as consistent with existing patterns as much as possible.
+-->
+
+We need to introduce new collection to save tokens.
+
+**tokens**
+  - bucketId - String
+  - fileId - String
+  - secret - String
+  - permissions - array string
+  - expiryDate - date time
+
+### Supporting Libraries
+
+<!--
+Which different libraries do we need to support the new features?
+Please describe the new library's potential API?
+Avoid using 3rd party libraries when possible, if required - explain why.
+-->
+
+This particular feature doesn't require any supporting libraries.
+
+### Breaking Changes
+
+<!--
+Do we break any API or SDK backward compatibility?
+If possible, explain what actions we can take to avoid that.
+-->
+
+
+### Reliability (Tests & Benchmarks)
+
+#### Scaling
+
+<!-- Explain how we will scale this new feature. -->
+This will be part of Appwrite core, which should scale along with the existing Appwrite infrastructure.
+
+#### Benchmarks
+
+<!-- Explain how we will benchmark the new feature. -->
+
+We don't need separate banchmark as this is part of Appwrite core API
+
+#### Tests (UI, Unit, E2E)
+
+<!-- 
+Explain how we will test the new feature. 
+You can use "N/A" if this section is not relevant to your proposal.
+-->
+
+We will write relevant Unit and E2E test for this feature.
+
+### Documentation & Content
+
+<!--
+
+Documentation is vital for making this new feature a success for both developers using Appwrite and the Appwrite maintainers.
+Please answer the following questions:
+
+1. What **docs** would support this feature?
+2. Do we need to update the **contribution guide** with a new section or a supporting tutorial?
+3. What **tutorials** (text/video) might help developers understand this feature scope, capabilities, and possible use-cases?
+4. What **demo applications** can help us demonstrate this feature APIs and capabilities? 
+
+-->
+
+### Prior art
+
+[prior-art]: #prior-art
+
+<!--
+
+Discuss prior art, both the good and the bad, in relation to this proposal.
+A few examples of what this can include are:
+
+- Does this functionality exist in other software, and what experience has their community had?
+- For other teams: What lessons can we learn from what other communities have done here?
+- Papers: Are there any published papers or great posts that discuss this? If you have some relevant papers to refer to, this can serve as a more detailed theoretical background.
+
+This section is intended to encourage you as an author to think about the
+lessons from other software, provide readers of your RFC with a fuller picture.
+If there is no prior art, that is fine - your ideas are interesting to us, whether they are brand new or an adaptation from other software.
+
+Write your answer below.
+-->
+
+### Unresolved questions
+
+[unresolved-questions]: #unresolved-questions
+
+<!-- What parts of the design do you expect to resolve through the RFC process before this gets merged? -->
+
+<!-- Write your answer below. -->
+
+### Future possibilities
+
+[future-possibilities]: #future-possibilities
+
+<!-- This is also a good place to "dump ideas" if they are out of scope for the RFC you are writing but otherwise related. -->
+
+<!-- Write your answer below. -->

From c435f2757965226b671eaf3223b92526d4d8e7b4 Mon Sep 17 00:00:00 2001
From: Damodar Lohani <dlohani48@gmail.com>
Date: Tue, 20 Jun 2023 07:03:55 +0000
Subject: [PATCH 2/6] more updates

---
 024-file-tokens.md | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git a/024-file-tokens.md b/024-file-tokens.md
index 1f6d095..fd54815 100644
--- a/024-file-tokens.md
+++ b/024-file-tokens.md
@@ -27,7 +27,7 @@ Please avoid discussing your proposed solution.
 
 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.
+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)
 
@@ -66,13 +66,13 @@ For example:
 **DELETE /v1/coffee ** - an endpoint for deleting coffee.
 -->
 
-We will introduce a new `Tokens` service, that will allow us to manage tokens.
+Tokens will be a part of storage service
 
-**POST /v1/tokens** -           create token
-**PUT /v1/tokens** -            update token
-**GET /v1/tokens** -            List token
-**GET /v1/tokens/:tokenId** -   Get token
-**DELETE /v1/tokens** -         delete token
+**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
@@ -110,6 +110,7 @@ Do we break any API or SDK backward compatibility?
 If possible, explain what actions we can take to avoid that.
 -->
 
+This shouldn't break any existing features
 
 ### Reliability (Tests & Benchmarks)
 
@@ -147,6 +148,10 @@ Please answer the following questions:
 
 -->
 
+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
@@ -182,3 +187,6 @@ Write your answer below.
 <!-- This is also a good place to "dump ideas" if they are out of scope for the RFC you are writing but otherwise related. -->
 
 <!-- Write your answer below. -->
+
+* Use token for other resources
+* More granular permission control to allow read/create/update/delete permissions to make something like google docs possible

From 09f24e9cf137a7a42629f5a5ebc7f27350c8f0cd Mon Sep 17 00:00:00 2001
From: Damodar Lohani <dlohani48@gmail.com>
Date: Tue, 27 Jun 2023 01:29:03 +0000
Subject: [PATCH 3/6] update

---
 024-file-tokens.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/024-file-tokens.md b/024-file-tokens.md
index fd54815..bf3eb14 100644
--- a/024-file-tokens.md
+++ b/024-file-tokens.md
@@ -93,6 +93,8 @@ We need to introduce new collection to save tokens.
   - permissions - array string
   - expiryDate - date time
 
+We will also need a token validator, that will validate that the token is not expired and has access to the resources.
+
 ### Supporting Libraries
 
 <!--
@@ -172,6 +174,8 @@ If there is no prior art, that is fine - your ideas are interesting to us, wheth
 Write your answer below.
 -->
 
+- File tokens are used by many similar services to provide file access.
+
 ### Unresolved questions
 
 [unresolved-questions]: #unresolved-questions
@@ -180,6 +184,9 @@ Write your answer below.
 
 <!-- Write your answer below. -->
 
+1. Token data structure to support different resources
+2. Token permission (read, write, update, delete), right now we only provide read permission
+
 ### Future possibilities
 
 [future-possibilities]: #future-possibilities

From 04e23b5fcebc2dc00fe15a596ca01b82704949af Mon Sep 17 00:00:00 2001
From: Damodar Lohani <lohanidamodar@users.noreply.github.com>
Date: Wed, 3 Jan 2024 06:52:00 +0545
Subject: [PATCH 4/6] Update data structure to support multiple resources
 instead of just files

---
 024-file-tokens.md | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/024-file-tokens.md b/024-file-tokens.md
index bf3eb14..f04e013 100644
--- a/024-file-tokens.md
+++ b/024-file-tokens.md
@@ -86,13 +86,16 @@ Appwrite conventions. Try and stay as consistent with existing patterns as much
 
 We need to introduce new collection to save tokens.
 
-**tokens**
-  - bucketId - String
-  - fileId - String
+**resourceTokens**
+  - resourceId - String
+  - resourceInternalId - String
+  - resourceType = String
   - secret - String
-  - permissions - array string
+  - secretHash - String (md5 hash of secret for query)
   - 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.
 
 ### Supporting Libraries
@@ -184,8 +187,7 @@ Write your answer below.
 
 <!-- Write your answer below. -->
 
-1. Token data structure to support different resources
-2. Token permission (read, write, update, delete), right now we only provide read permission
+1. Token permission (read, write, update, delete), right now we only provide read permission
 
 ### Future possibilities
 

From c59f8b2cb34dc46943f8779b6e187536e955022d Mon Sep 17 00:00:00 2001
From: Damodar Lohani <lohanidamodar@users.noreply.github.com>
Date: Thu, 4 Jan 2024 08:00:29 +0545
Subject: [PATCH 5/6] update RFC

---
 024-file-tokens.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/024-file-tokens.md b/024-file-tokens.md
index f04e013..0824f04 100644
--- a/024-file-tokens.md
+++ b/024-file-tokens.md
@@ -91,13 +91,16 @@ We need to introduce new collection to save tokens.
   - resourceInternalId - String
   - resourceType = String
   - secret - String
-  - secretHash - String (md5 hash of secret for query)
   - 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
 
 <!--
@@ -106,7 +109,7 @@ Please describe the new library's potential API?
 Avoid using 3rd party libraries when possible, if required - explain why.
 -->
 
-This particular feature doesn't require any supporting libraries.
+We will be using JWT to create token that has the payload `tokenId`, `resourceId`, `resourceType` and `expiryDate`
 
 ### Breaking Changes
 

From a80cae8bad5e001b6ba628275b39ec9a3fa8c02f Mon Sep 17 00:00:00 2001
From: Damodar Lohani <lohanidamodar@users.noreply.github.com>
Date: Thu, 4 Jan 2024 08:02:06 +0545
Subject: [PATCH 6/6] rename collection

---
 024-file-tokens.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/024-file-tokens.md b/024-file-tokens.md
index 0824f04..bea833e 100644
--- a/024-file-tokens.md
+++ b/024-file-tokens.md
@@ -86,7 +86,7 @@ Appwrite conventions. Try and stay as consistent with existing patterns as much
 
 We need to introduce new collection to save tokens.
 
-**resourceTokens**
+**resource_tokens**
   - resourceId - String
   - resourceInternalId - String
   - resourceType = String