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"]

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