Tiptap Collaboration and General Authorization Policies

[calebbourg]

Tiptap

Tiptap requires 2 pieces of information to successfully load an existing document:

• name: An arbitrary string, which uniquely identifies a document
  • This value is provided by our system when a new document is created.
  • The name can take any string value. Values like jim-caleb-1, or jim/{UUID} or {UUID/UUID} are all valid
• token: A signed JWT which includes information describing which documents the holder (user) of the JWT can access
  • The token can include a allowedDocumentNames field which is an array of document names for which the holder of the JWT can access.
  • allowedDocumentNames supports wildcard patterns. Ex. jim-caleb/* which would allow the holder of the JWT to access all documents that have names that start with jim-caleb/ Ex. jim-caleb/{coaching_session_id}

General Authorization Policies

We can categorize all current resources represented in the system into 3 groups:

• Resources created within the context of an Organization
• Resources created within the context of a Coaching Relationship
• Resources created by a User

Other things to note:

• In each case the resource may or may not be directly associated with the entity.
• Resources can, and often will, belong to multiple groups. Ex. a note is created by a User in the context of a Coaching Relationship within an Organization
• Some Resources that are created by a specific User should allow for that user to choose to be the only one able to access that resource. Ex. A Coach or Coachee may want to maintain a set of private notes for their personal use within the platform.

Proposal

General

• Each time an actor (User but could be another component of the system in the future) attempts to access a resource, we evaluate permissions based on the following general policies:
  • A User has read access to all resources relating to a Coaching Relationship for which they are a Coach or a Coachee.
  • A User has read/write access to all resources that they created.
• Resources that allow for a User to manage which other Users have access will be associated with a visibility enum with (to start) variants Self, coaching_relationship, and organization
  • Resources with visibility: Self will be considered private and only accessible by the User that created the resource.
  • Resources with visibility: coaching_relationship will be accessible to each User associated with the coaching_relationship to which the resource belongs.
  • Resources will be created with a default visibility of coaching_relationship

Tiptap

• A new Tiptap JWT will be generated each time a user changes their Coaching Relationship (implies changes of Organization as well)
  • This means we will need to encode the JWT holder's full permissions related to Tiptap scoped to the current Coaching Relationship at the time the user chooses a Coaching Relationship
• Tiptap documents may be associated with different Refactor resources but will only be directly associated with a single resource at any given time. Ex. document is associated with a note or a coaching_session but not directly associated with both.
• We use Tiptaps wildcard support to organize documents:
  • Add a slug column to organizations and coaching_relationships tables.
  • Document names are prefixed by arbitrary nesting of slugs and terminated with the UUID of the owning resource. Ex {organization_slug/{coaching_relationship_slug}/{note_UUID}
  • A JWT held by Caleb in this context might include allowedDocumentNames: ["jim-hodapp-coaching/jim-caleb/*"] which would allow Caleb access to all Tiptap documents associated with the jim-caleb Coaching Relationship

Diagrams

General

flowchart TD
    A[Start] --> B["User attempts to access a resource"]
    B --> C{"Evaluate permissions"}
    
    C --> |Creator?| D{"Is User the Creator?"}
    D --> |Yes| E["Grant read/write access"]
    
    D --> |No| F{"Is User a Coach or Coachee in related Coaching Relationship?"}
    F --> |Yes| G["Grant read access"]
    
    F --> |No| H{"Check resource visibility"}
    
    H --> |"Self"| I{"Is User the Creator?"}
    I --> |Yes| J["Grant access"]
    I --> |No| K["Deny access"]
    
    H --> |"coaching_relationship"| L{"Is User in related Coaching Relationship?"}
    L --> |Yes| M["Grant access"]
    L --> |No| N["Deny access"]
    
    H --> |"organization (future)"| P{"Is User in Organization?"}
    P --> |Yes| Q["Grant access"]
    P --> |No| R["Deny access"]

Loading

TipTap

flowchart TD
    subgraph "JWT Generation"
        A[User changes Coaching Relationship] --> B[Generate new Tiptap JWT]
        B --> C[Encode full permissions for current Coaching Relationship]
    end

    subgraph "Document Creation"
        C --> D[Create document name prefix]
        D --> E["{organization_slug}/{coaching_relationship_slug}/"]
        E --> G[Append resource UUID to document name]
        H --> F["{organization_slug}/{coaching_relationship_slug}/{{resource_type}_UUID}"]
        G[Create Tiptap document] --> H[Associate with single Refactor resource]
    end
    
    subgraph "Access Control"
        J[User attempts to access Tiptap document] --> K{Check JWT permissions: matches Coaching Relationship e.g.: 'jim-hodapp-coaching/jim-caleb/*'?}
        K --> |Yes| L[Grant access]
        K --> |No| M[Deny access]
    end

    subgraph Example: Caleb's JWT
        N[Start] --> O["allowedDocumentNames: ['jim-hodapp-coaching/jim-caleb/*']"]
        O --> P[Caleb can access all documents in jim-caleb Coaching Relationship]
    end

Loading

[jhodapp]

@calebbourg Your proposal looks great, thank you for proposing it.

Adding some flow charts to your original proposal to help us visualize it. Some follow-up questions I have:

1. Where does the JWT check (diagram 2) fit into the auth check in diagram 1?
2. Where does our frontend application fit into these auth check flows? It'd be helpful to see it as a generic "Frontend" box where appropriate.
3. It'd be helpful to see where TipTap's collaboration server fits into the auth check flows, similar to visualizing how our frontend is represented.