adr: Add a Flow read-write permissions ADR

api/TimeAddressableMediaStore.yaml

@@ -486,6 +486,58 @@ paths:
       responses:
         "204":
           description: No content. The flow description property has been deleted.
+  /flows/{flowId}/read_only:
+    parameters:
+      - name: flowId
+        in: path
+        required: true
+        schema:
+          $ref: '#/components/schemas/uuid'
+        description: The flow identifier.
+    head:
+      description: Return flow read_only path headers
+      operationId: HEAD_flows-flowId-read-only
+      tags:
+        - Flows
+      responses:
+        "200":
+          $ref: '#/components/responses/trait_resource_info_head_200'
+        "400":
+          $ref: '#/components/responses/trait_resource_info_head_400'
+        "404":
+          $ref: '#/components/responses/trait_resource_info_head_404'
+    get:
+      description: Returns the flow read_only property.
+      operationId: GET_flows-flowId-read-only
+      tags:
+        - Flows
+      responses:
+        "200":
+          description: ""
+          content:
+            application/json:
+              example:
+                $ref: examples/flow-read-only-get-200.json
+        "404":
+          description: The requested flow does not exist.
+    put:
+      description: Set the read-only property.
+      operationId: PUT_flows-flowId-read-only
+      tags:
+        - Flows
+      requestBody:
+        content:
+          application/json:
+            example:
+              $ref: examples/flow-read-only-put.json
+            schema:
+              type: boolean
+        required: true
+      responses:
+        "204":
+          description: No content. The read_only property has been updated.
+        "400":
+          description: Bad request. Invalid flow description.
   /flows/{flowId}/segments:
     parameters:
       - name: flowId

api/examples/flow-read-only-get-200.json

@@ -0,0 +1 @@
+true

api/examples/flow-read-only-put.json

@@ -0,0 +1 @@
+true

api/schemas/flow-core.json

@@ -67,6 +67,10 @@
       "type": "string",
       "format": "date-time"
     },
+    "read_only": {
+      "description": "If set to 'true', implementations SHOULD reject client requests to update Flow metadata (other than the read_only property), Flow Segments and media objects",
+      "type": "boolean"
+    },
     "codec": {
       "description": "A MIME type identification of the (lossy or lossless) coding used for the flow content.",
       "type": "string",

docs/adr/decisions/0005-flow-read-write-permissions.md

@@ -0,0 +1,61 @@
+---
+status: "accepted"
+---
+# Flow Read-Write Permissions
+
+## Context and Problem Statement
+
+A Flow read-only permission could be set to protect the Flow from unintended changes to the metadata, Flow Segments and media objects once it is complete.
+This is a very basic form of access permissions for Flows that could be extended in future to include things such as users, roles, projects etc.
+
+## Decision Drivers
+
+* Balance providing useful features and avoiding complexity in the TAMS design
+
+## Considered Options
+
+* Option 1: Rely on users to not update a Flow
+* Option 2: Add a boolean `read_only` property to set whether updates are permitted or not
+* Option 3: Design a more extensive permissions model
+
+## Decision Outcome
+
+Chosen option: Option 2: Add a boolean `read_only` property to set whether updates are permitted or not.
+
+Option 2 was agreed to be a sensible stopgap, to provide some protection against unintended mistakes without adding undue complexity.
+
+### Implementation
+
+Implemented by [https://github.com/bbc/tams/pull/24](https://github.com/bbc/tams/pull/24).
+
+## Pros and Cons of the Options
+
+### Option 1: Rely on users to not update a Flow
+
+This is the current state.
+
+* Good, because the implementation doesn't need to determine whether a request is permitted or not
+* Bad, because Flows can easily be updated unintentionally
+
+### Option 2: Add a boolean `read_only` property to set whether updates are permitted or not
+
+If the `read_only` property is set to `true` then the implementation will reject attempts to update the Flow metadata or Flow Segments.
+If the `read_only` property is handled by the media object storage as well then it would also reject attempts to update the media objects (e.g. deleting media objects or bypassing the `/storage` endpoint to write media objects).
+
+* Good, because it allows unintentional changes to be prevented
+* Bad, because users are still allowed to change the `read_only` property and then make updates
+* Bad, because users could still make changes to media objects if the storage doesn't handle the `read_only` property
+
+### Option 3: Design a more extensive permissions model
+
+* Good, because it allow finer grained control of which users can make updates
+* Bad, because it adds complexity to the store and requires design work
+
+## More Information
+
+### TAMS/AWS Workshop Discussion - 13th February 2024
+
+A discussion about this proposal took place during the TAMS/AWS workshop on 13th February 2024, with the BBC R&D TAMS team, BBC B&EUT architects and AWS Solution Architects.
+
+This discussion quickly concluded that Option 3 was the ideal, but requires considerable research and consideration, some of which may not be possible without a broader understanding of real world use cases.
+Option 2 was agreed to be a sensible stopgap, to provide some protection against unintended mistakes without adding undue complexity.