Add invite feature

Author: TimCsaky

docs/Endpoint-Notes.md

@@ -10,6 +10,7 @@ This page outlines the general usage patterns and organization of the COMS API.
   - [Tag](#tag)
   - [Versions](#versions)
 - [Permission](#permission)
+- [Invite URL's](#invite-urls)
 - [Sync](#sync)
 - [User](#user)
 
@@ -31,27 +32,31 @@ Object endpoints directly influence and manipulate S3 objects and information in
   - Calling in the Delete endpoint on a bucket without versioning is a hard-delete.
 - The `GET /object` search and `PATCH /object/{objectId}/public` public toggle require a backing database in order to function.
 
-### Metadata
+## Metadata
 
 Metadata operation endpoints directly focus on the manipulation of metadata of S3 Objects. Each endpoint will create a copy of the object with the modified metadata attached.
 
 More details found here: [Metadata and Tags](Metadata-Tag.md)
 
-### Tag
+## Tag
 
 Tag operation endpoints directly focus on the manipulation of tags of S3 Objects. Unlike Metadata, Tags can be modified without the need to create new versions of the object.
 
 More details found here: [Metadata and Tags](Metadata-Tag.md)
 
-### Versions
+## Versions
 
 Version specific operations focus on listing and discovering versioning information known by COMS. While the majority of version-specific operations are available as query parameters in the Objects endpoints, the `GET /object/{objectId}/version` endpoint focuses on letting users discover and list what versions are available to work with.
 
-## Permission
+## Permissions
 
 Permission operation endpoints directly focus on associating users to objects with specific permissions. All of these endpoints require a database to function. Existing permissions can be searched for using `GET /permission/object` and `GET /permission/bucket`, and standard create, read and delete operations for permissions exist to allow users to modify access control for specific objects they have management permissions over.
 
-More details found here: [Permissions](Permissions.md)
+## Invite URL's
+
+COMS also offers a user invite feature. Generate a time-limited, single use invitation token which can be used by an authenticated user to acquire `READ` or other permissions to a specific resource (object or bucket). Optional email-user validation may be specified to ensure the link is only used by the intended recipient. To create an invite link one must have the MANAGE permission on the resource being shared.
+
+See [API Specification](https://coms.api.gov.bc.ca/api/v1/docs#tag/Permission/operation/createInvite)
 
 ## Sync
 

docs/Permissions.md

@@ -10,7 +10,7 @@ This page outlines the general design used for managing User Access Control to S
     - [Examples](#examples)
     - [Response Scope Expansion](#response-scope-expansion)
   - [Mode Considerations](#mode-considerations)
-- [Overrides](#overrides)
+- [Invite Links](#invite-links)
   - [Public](#public)
 
 ## Overview
@@ -171,9 +171,11 @@ The above permission system will only be enforced if your instance of COMS is ru
 
 For more specific information on COMS deployment modes and how they differ, please take a look at the COMS [Configuration guide](Configuration#authentication-modes).
 
-## Overrides
+## Invite Links
 
-While the COMS DAC model is generally precise about what users are able to do, there are specific escape hatches and situations where the DAC is superceded or ignored by COMS for a different ruleset. This is done because while the DAC is rich and capable of expressing many access control needs, there are situations where the user may not be known in advance, and as such binding a permission to the potential user is not possible.
+COMS also offers a user invite feature. Generate a time-limited, single use invitation token which can be used by an authenticated user to acquire `READ` or other permissions to a specific resource (object or bucket). Optional email-user validation may be specified to ensure the link is only used by the intended recipient. To create an invite link one must have the MANAGE permission on the resource being shared.
+
+See [API Specification](https://coms.api.gov.bc.ca/api/v1/docs#tag/Permission/operation/createInvite)
 
 ### Public
 

docs/Synchronization.md

@@ -4,24 +4,24 @@ However, as there is no mechanism for S3 to directly notify COMS of any changes,
 
 To avoid this, COMS can be told to **synchronize** a bucket, where it looks at a S3 bucket it manages and updates the entries in its database, matching what's actually in the bucket.
 
-## The synchronization process
+## The Synchronization process
 
 Clients can trigger the sync process through a [set of dedicated API endpoints](https://coms.api.gov.bc.ca/api/v1/docs#tag/Sync).
 
 When these endpoints are called, COMS checks both the S3 bucket and its database for a list of objects in the bucket, merges them into a single list without duplicates, and enqueues each resulting object (or **job**) into a shared queue in the COMS database, before returning the number of objects enqueued.
 
 The actual synchronization is handled by a separate sync service, which polls the database queue for new jobs every 10 seconds. Once a job is picked up, it compares the corresponding object's state in both S3 and COMS; in particular, it looks at whether it exists in either S3 or COMS (that is, whether it's a new or deleted file), as well as its tags and metadata, and updates the database accordingly.
 
-![COMS sync flow](images/coms_sync_flow.png)
+![COMS sync flow](images/coms_sync_flow.png)<br />
 **Figure 1 - an illustration of the sync process**
 
-### The `queueManager` service
+## The `queueManager` service
 
 The actual sync work is performed by the `queueManager` (labeled "Sync service" in the sequence diagram above), which is on a thread separate from the COMS API.
 
 Every 10 seconds, it polls the queue, which is implemented as a database table named `object_queue`. If the queue is empty, it goes back to waiting for another ten seconds.
 
 If the queue is not empty, it grabs a job from it, and performs the sync process on the associated file. Once it completes that process, it checks the queue for another job to process. If the queue is empty, it goes back to waiting for another 10 seconds before polling the queue again.
 
-![queueManager state](images/queue_manager_state.png)
-**Figure 2 - an illustration of `queueManager`'s possible states, as it polls the queue and performs sync jobs.**
+![queueManager state](images/queue_manager_state.png)<br />
+**Figure 2 - an illustration of queueManager's possible states, as it polls the queue and performs sync jobs.**

docs/Use-Case-Examples.md

@@ -30,6 +30,6 @@ The following steps describe how a document management interface in your applica
 6. `User B` logs in to the client application.
 7. Client application makes request to [Read Object](https://coms.api.gov.bc.ca/api/v1/docs#tag/Object/operation/readObject) endpoint (with User B's JWT in an Authorization header)
     - COMS will verify User B using the JWT and look up permissions for the file in the COMS database
-    - COMS will then respond with a redirect to a pre-signed url to the source object in the storage server or allow direct download via proxy. Read the section on [OIDC AUthentication](Authentication#authentication-flow-for-readobject) for more details.
+    - COMS will then respond with a redirect to a pre-signed url to the source object in the storage server or allow direct download via proxy. Read the section on [OIDC AUthentication](Authentication.md#authentication-flow-for-readobject) for more details.
 
 For full implementation details of the COMS API, visit the [BCBox](https://github.com/bcgov/bcbox) repository.

docs/index.md

@@ -6,7 +6,8 @@ Take advantage of more cost-effective storage solutions for your new or existing
 
 ## Onboarding Options
 
-COMS is now available as a shared hosted service as well as an application that you can customise and deploy in your own infrastructure. See documentation on [Hosting Considerations](Hosting-Considerations.md).
+COMS is now available as a shared hosted service as well as an application that you can customise and deploy in your own infrastructure.<br />
+See documentation on [Hosting Considerations](Hosting-Considerations.md).
 
 We have also launched [BCBox](https://bcbox.nrs.gov.bc.ca), a DropBox-like user-interface for managing files, integrated with the hosted COMS service.
 
@@ -29,8 +30,7 @@ Please follow the links in the side menu to learn more about COMS.
 - GitHub Repository: [https://github.com/bcgov/common-object-management-service/](https://github.com/bcgov/common-object-management-service/)
 - API Specification: [https://coms.api.gov.bc.ca/api/v1/docs](https://coms.api.gov.bc.ca/api/v1/docs)
 - UI Integration: [BCBox](https://bcbox.nrs.gov.bc.ca)
-
-**[Product Roadmap](Product-Roadmap.md)**
+- **[Product Roadmap](Product-Roadmap.md)**
 
 ***