From 45de72ba111e7cc233be5bb2c97a32b4b543d604 Mon Sep 17 00:00:00 2001 From: James Sandford Date: Thu, 2 Jul 2026 11:01:51 +0100 Subject: [PATCH 1/7] Add the ability to select if put_urls are pre-signed sem-ver: feature --- api/schemas/flow-storage-post.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/api/schemas/flow-storage-post.json b/api/schemas/flow-storage-post.json index fdb785ef..94d7cc01 100644 --- a/api/schemas/flow-storage-post.json +++ b/api/schemas/flow-storage-post.json @@ -21,6 +21,10 @@ "content_type": { "description": "The `content_type` to use for the Objects. This parameter MUST only be set where requesting storage for initialisation segments in media formats which require them, and where the mime-type of those initialisation segments differs to that of the media segments. Assumed to be the `container` type of the Flow if not set.", "$ref": "mime-type.json" + }, + "presigned": { + "description": "If set to `true`, the `put_url`'s in the response will be presigned. If set to `false`, the `put_url`'s in the response will not be presigned. If `presigned` is set to `false`, the response from the service could be substantially faster if it is not required to generate a large number of pre-signed URLs. Services may choose their own default. If Clients only support one mode of operation, they SHOULD specify this parameter.", + "type": "boolean" } }, "not": { From 6d9c74e0d06961fb7a306b0ad729e0f5bd48fad7 Mon Sep 17 00:00:00 2001 From: James Sandford Date: Thu, 2 Jul 2026 11:02:13 +0100 Subject: [PATCH 2/7] Add explicit signalling as to if put_urls are pre-signed --- api/schemas/flow-storage.json | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/api/schemas/flow-storage.json b/api/schemas/flow-storage.json index 9abd76e3..1341cebf 100644 --- a/api/schemas/flow-storage.json +++ b/api/schemas/flow-storage.json @@ -20,7 +20,11 @@ }, "put_url": { "$ref": "http-request.json" - } + }, + "presigned": { + "description": "If `true`, this URL is pre-signed. If this parameter is unset, the URL is NOT pre-signed. The presigned URL SHALL remain valid for the timeframe advertised in [`min_presigned_url_timeout` at the `/service`](#/operations/GET_service) endpoint, which is subject to a specified minimum (see service endpoint schema).", + "type": "boolean" + }, } } } From 60e97bd8c85e9828d5a90063aee7e095192fcc2f Mon Sep 17 00:00:00 2001 From: James Sandford Date: Thu, 2 Jul 2026 11:04:43 +0100 Subject: [PATCH 3/7] Provide greater clarity on authentication methods for put_urls and get_urls --- api/TimeAddressableMediaStore.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/api/TimeAddressableMediaStore.yaml b/api/TimeAddressableMediaStore.yaml index 2c93eb02..9d1becee 100644 --- a/api/TimeAddressableMediaStore.yaml +++ b/api/TimeAddressableMediaStore.yaml @@ -2392,7 +2392,7 @@ paths: Where Flow Segments reference initialisation segment Objects with the same ID, the initialisation segment is the same. Consuming clients may choose to ignore initialisation segment Objects that haven't changed in subsequent Flow Segments. - When making requests to the provided `get_urls`, clients should include credentials if the provided URL is on the same origin as the API itself, akin to the `same-origin` mode in the [WhatWG Fetch Standard](https://fetch.spec.whatwg.org/#concept-request-credentials-mode). + When making requests to provided `get_url`'s that are not presigned, clients SHOULD include credentials if the provided URL is on the same origin as the Service itself, akin to the `same-origin` mode in the [WhatWG Fetch Standard](https://fetch.spec.whatwg.org/#concept-request-credentials-mode). Services MAY support the use of out-of-band credentials where the provided URL is on a different origin to the Service itself. Services SHOULD NOT solely require the use of out-of-band credentials. operationId: GET_flows-flowId-segments tags: - FlowSegments @@ -2681,7 +2681,7 @@ paths: Service implementations need to handle situations where Objects are not used, and where content is were uploaded but the Object is not successfully registered against a Flow Segment or as an init Object against Media Objects. In these circumstances, Services should garbage collect Objects after the timeout advertised in [`min_object_timeout` at the `/service`](#/operations/GET_service) endpoint. - When making requests to the provided `put_url`, clients should include credentials if the provided URL is on the same origin as the API itself, akin to the `same-origin` mode in the [WhatWG Fetch Standard](https://fetch.spec.whatwg.org/#concept-request-credentials-mode). + When making requests to provided `put_url`'s that are not presigned, clients SHOULD include credentials if the provided URL is on the same origin as the Service itself, akin to the `same-origin` mode in the [WhatWG Fetch Standard](https://fetch.spec.whatwg.org/#concept-request-credentials-mode). Services MAY support the use of out-of-band credentials where the provided URL is on a different origin to the Service itself. Services SHOULD NOT solely require the use of out-of-band credentials. operationId: POST_flows-flowId-storage tags: - MediaStorage @@ -2832,6 +2832,8 @@ paths: The paging query parameters and headers are required for the list of Flow references in the Object. Service implementations should return a complete list of Flow references within reason and API clients should expect paging to happen in some rare cases where a Object is used in many Flows. + + When making requests to provided `get_url`'s that are not presigned, clients SHOULD include credentials if the provided URL is on the same origin as the Service itself, akin to the `same-origin` mode in the [WhatWG Fetch Standard](https://fetch.spec.whatwg.org/#concept-request-credentials-mode). Services MAY support the use of out-of-band credentials where the provided URL is on a different origin to the Service itself. Services SHOULD NOT solely require the use of out-of-band credentials. operationId: GET_objects tags: - Objects From 8f5031ce6d7c781708da09bbeb5df006133bf3d8 Mon Sep 17 00:00:00 2001 From: James Sandford Date: Tue, 7 Jul 2026 14:06:28 +0100 Subject: [PATCH 4/7] Grammar fixes following review --- api/TimeAddressableMediaStore.yaml | 6 +++--- api/schemas/flow-storage-post.json | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/api/TimeAddressableMediaStore.yaml b/api/TimeAddressableMediaStore.yaml index 9d1becee..be475d71 100644 --- a/api/TimeAddressableMediaStore.yaml +++ b/api/TimeAddressableMediaStore.yaml @@ -2392,7 +2392,7 @@ paths: Where Flow Segments reference initialisation segment Objects with the same ID, the initialisation segment is the same. Consuming clients may choose to ignore initialisation segment Objects that haven't changed in subsequent Flow Segments. - When making requests to provided `get_url`'s that are not presigned, clients SHOULD include credentials if the provided URL is on the same origin as the Service itself, akin to the `same-origin` mode in the [WhatWG Fetch Standard](https://fetch.spec.whatwg.org/#concept-request-credentials-mode). Services MAY support the use of out-of-band credentials where the provided URL is on a different origin to the Service itself. Services SHOULD NOT solely require the use of out-of-band credentials. + When making requests to provided `get_url`s that are not presigned, clients SHOULD include credentials if the provided URL is on the same origin as the Service itself, akin to the `same-origin` mode in the [WhatWG Fetch Standard](https://fetch.spec.whatwg.org/#concept-request-credentials-mode). Services MAY support the use of out-of-band credentials where the provided URL is on a different origin to the Service itself. Services SHOULD NOT solely require the use of out-of-band credentials. operationId: GET_flows-flowId-segments tags: - FlowSegments @@ -2681,7 +2681,7 @@ paths: Service implementations need to handle situations where Objects are not used, and where content is were uploaded but the Object is not successfully registered against a Flow Segment or as an init Object against Media Objects. In these circumstances, Services should garbage collect Objects after the timeout advertised in [`min_object_timeout` at the `/service`](#/operations/GET_service) endpoint. - When making requests to provided `put_url`'s that are not presigned, clients SHOULD include credentials if the provided URL is on the same origin as the Service itself, akin to the `same-origin` mode in the [WhatWG Fetch Standard](https://fetch.spec.whatwg.org/#concept-request-credentials-mode). Services MAY support the use of out-of-band credentials where the provided URL is on a different origin to the Service itself. Services SHOULD NOT solely require the use of out-of-band credentials. + When making requests to provided `put_url`s that are not presigned, clients SHOULD include credentials if the provided URL is on the same origin as the Service itself, akin to the `same-origin` mode in the [WhatWG Fetch Standard](https://fetch.spec.whatwg.org/#concept-request-credentials-mode). Services MAY support the use of out-of-band credentials where the provided URL is on a different origin to the Service itself. Services SHOULD NOT solely require the use of out-of-band credentials. operationId: POST_flows-flowId-storage tags: - MediaStorage @@ -2833,7 +2833,7 @@ paths: The paging query parameters and headers are required for the list of Flow references in the Object. Service implementations should return a complete list of Flow references within reason and API clients should expect paging to happen in some rare cases where a Object is used in many Flows. - When making requests to provided `get_url`'s that are not presigned, clients SHOULD include credentials if the provided URL is on the same origin as the Service itself, akin to the `same-origin` mode in the [WhatWG Fetch Standard](https://fetch.spec.whatwg.org/#concept-request-credentials-mode). Services MAY support the use of out-of-band credentials where the provided URL is on a different origin to the Service itself. Services SHOULD NOT solely require the use of out-of-band credentials. + When making requests to provided `get_url`s that are not presigned, clients SHOULD include credentials if the provided URL is on the same origin as the Service itself, akin to the `same-origin` mode in the [WhatWG Fetch Standard](https://fetch.spec.whatwg.org/#concept-request-credentials-mode). Services MAY support the use of out-of-band credentials where the provided URL is on a different origin to the Service itself. Services SHOULD NOT solely require the use of out-of-band credentials. operationId: GET_objects tags: - Objects diff --git a/api/schemas/flow-storage-post.json b/api/schemas/flow-storage-post.json index 94d7cc01..d3d96fae 100644 --- a/api/schemas/flow-storage-post.json +++ b/api/schemas/flow-storage-post.json @@ -23,7 +23,7 @@ "$ref": "mime-type.json" }, "presigned": { - "description": "If set to `true`, the `put_url`'s in the response will be presigned. If set to `false`, the `put_url`'s in the response will not be presigned. If `presigned` is set to `false`, the response from the service could be substantially faster if it is not required to generate a large number of pre-signed URLs. Services may choose their own default. If Clients only support one mode of operation, they SHOULD specify this parameter.", + "description": "If set to `true`, the `put_url`s in the response will be presigned. If set to `false`, the `put_url`s in the response will not be presigned. If `presigned` is set to `false`, the response from the service could be substantially faster if it is not required to generate a large number of pre-signed URLs. Services may choose their own default. If Clients only support one mode of operation, they SHOULD specify this parameter.", "type": "boolean" } }, From 5beafa515181320b7eb022d7cb8b43f15783376b Mon Sep 17 00:00:00 2001 From: James Sandford Date: Wed, 15 Jul 2026 16:55:36 +0100 Subject: [PATCH 5/7] Remove trailing comma from flow-storage schema --- api/schemas/flow-storage.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/schemas/flow-storage.json b/api/schemas/flow-storage.json index 1341cebf..ffae93c3 100644 --- a/api/schemas/flow-storage.json +++ b/api/schemas/flow-storage.json @@ -24,7 +24,7 @@ "presigned": { "description": "If `true`, this URL is pre-signed. If this parameter is unset, the URL is NOT pre-signed. The presigned URL SHALL remain valid for the timeframe advertised in [`min_presigned_url_timeout` at the `/service`](#/operations/GET_service) endpoint, which is subject to a specified minimum (see service endpoint schema).", "type": "boolean" - }, + } } } } From 910752327028b42f19070f67d2a676cb38fe1d4c Mon Sep 17 00:00:00 2001 From: James Sandford Date: Thu, 16 Jul 2026 15:51:28 +0100 Subject: [PATCH 6/7] Add ADR0054 on support for selectable presigned storage PUT URLs --- docs/README.md | 15 +-- .../0054-selectable-presigned-storage-urls.md | 101 ++++++++++++++++++ 2 files changed, 109 insertions(+), 7 deletions(-) create mode 100644 docs/adr/0054-selectable-presigned-storage-urls.md diff --git a/docs/README.md b/docs/README.md index 45c0f0c6..90a30325 100644 --- a/docs/README.md +++ b/docs/README.md @@ -80,16 +80,17 @@ For more information on how we use ADRs, see [here](./adr/README.md). | [0037](./adr/0037-improve-webhooks.md) | Proposal for improvements to the Webhooks endpoints | | [0038](./adr/0038-improved-storage-management.md) | Improved Storage Management | | [0039](./adr/0039-remove-pre-actions.md) | Proposal to remove pre-actions from storage allocation response | -| [0040](./adr/0040-tag-usability-enhancements.md) | Tag Usability Enhancements | -| [0041](./adr/0041-require-explicit-framerate.md) | Requiring explicit frame rates | -| [0042](./adr/0042-uncontrolled-object-instance-labels.md) | Make `label` Mandatory for Uncontrolled Object Instances | -| [0043](./adr/0043-signalling-retention-time.md) | Signalling retention time | -| [0044](./adr/0044-signalling-timeouts.md) | Signalling timeout periods | -| [0045](./adr/0045-flow-init-segments.md) | Support for init Segments in Flows | -| [0046](./adr/0046-governance.md) | Governance | +| [0040](./adr/0040-tag-usability-enhancements.md) | Tag Usability Enhancements | +| [0041](./adr/0041-require-explicit-framerate.md) | Requiring explicit frame rates | +| [0042](./adr/0042-uncontrolled-object-instance-labels.md) | Make `label` Mandatory for Uncontrolled Object Instances | +| [0043](./adr/0043-signalling-retention-time.md) | Signalling retention time | +| [0044](./adr/0044-signalling-timeouts.md) | Signalling timeout periods | +| [0045](./adr/0045-flow-init-segments.md) | Support for init Segments in Flows | +| [0046](./adr/0046-governance.md) | Governance | | [0047](./adr/0047-flow-profiles.md) | Adding Flow Profiles to TAMS | | [0048](./adr/0048-media-integrity.md) | Integrity model for media in TAMS, and when interacting with other systems | | [0052](./adr/0052-specifying-the-sorting-of-listings.md) | Options for specifying the sorting of listings | +| [0054](./adr/0054-selectable-presigned-storage-urls.md) | Support for selectable presigned storage PUT URLs | | [0055](./adr/0055-fine-grained-auth-storage-backends.md) | Support for Fine-Grained Authorisation on Storage Backends | \* Note: ADR 0004a was the unintended result of a number clash in the early development of TAMS which wasn't caught before publication diff --git a/docs/adr/0054-selectable-presigned-storage-urls.md b/docs/adr/0054-selectable-presigned-storage-urls.md new file mode 100644 index 00000000..fabe0cf2 --- /dev/null +++ b/docs/adr/0054-selectable-presigned-storage-urls.md @@ -0,0 +1,101 @@ +--- +status: "proposed" +--- +# Support for selectable presigned storage PUT URLs + +## Context and Problem Statement + +TAMS allows Client's to select whether `get_urls` for Objects returned by the `/objects/` and `/flows//segments` endpoints are pre-signed or not. +The `/flows//storage` endpoint does not have an equivalent feature for `put_url`s. +It states that Clients should include credentials if the provided URL is on the same origin as the API itself, akin to the same-origin mode in the [WhatWG Fetch Standard](https://fetch.spec.whatwg.org/#concept-request-credentials-mode). +In practice, many Service implementations return pre-signed URLs instead. + +Furthermore, the available options for storage URL authentication can present issues for business with mature security architecture policies that may be incompatible. + +This ADR presents options for rationalising our approach to storage URLs and supporting varied security architectures. + +## Considered Options + +* Option 1: Maintain the current approach +* Option 2: Add query parameter allowing Clients to select presigned/non-presigned PUT URLs +* Option 2a: Define a default when this parameter is unset +* Option 3: Add attribute to signal if returned URLs are presigned +* Option 4: Allow out-of-band credentials in some cases +* Option 5: Allow Service Implementations to solely use out-of-band credentials +* Option 6: Return a list of PUT URLs on the `/flows//storage` endpoint + +## Decision Outcome + +Chosen options 2, 3, and 4. +This provides improved alignment between storage PUT and GET URLs. +It explicitly signals which auth methods Clients should use with these URLs. +It provides improved flexibility in deployment security models. +It avoids potential security holes. + +### Implementation + +Implemented in [PR #222](https://github.com/bbc/tams/pull/222). + +## Pros and Cons of the Options + +### Option 1: Maintain the current approach + +This option would see no changes made. + +* Good, because it doesn't require any spec changes +* Bad, because it is inflexible in terms of authentication methods with PUT URLs +* Bad, because PUT and GET URL approaches differ +* Bad, because popular Service Implementations do not implement the specified auth method + +### Option 2: Add query parameter allowing Clients to select presigned/non-presigned PUT URLs + +This option would see a `presigned` query parameter added to the `/flows//storage` endpoint that is akin to that on the `/flows//segments` and `/objects/` endpoints. +If Option 6 is not chosen, the `If omitted, both presigned and non-presigned URLs will be returned.` sentence will be omitted as it only makes sense where multiple URLs are returned for the same Object. + +* Good, because it is flexible in terms of authentication methods with PUT URLs +* Good, because PUT and GET URL approaches will be aligned +* Good, because it supports the auth methods used by popular Service Implementations +* Neutral, because it requires a non-breaking API change + +### Option 2a: Define a default when this parameter is unset + +If Option 6 is not chosen, this Option would see a different default specified. +It neither this Option and Option 6 are chosen, Service Implementations would be allowed to choose their own default. + +* Good, because it provides clear expectations to the Client on default behaviour +* Bad, because it may be a breaking change for some Service Implementations +* Bad, because the chosen default may be incompatible with some deployment's security architecture + +### Option 3: Add attribute to signal if returned URLs are presigned + +This option would see an attribute added to the Flow Storage schema to explicitly signal if a returned URL is presigned, akin to that on the `/flows//segments` and `/objects/` endpoints. + +* Good, because it explicitly signals if a URL is presigned or not +* Good, because PUT and GET URL approaches will be aligned +* Neutral, because it requires a non-breaking API change + +### Option 4: Allow out-of-band credentials in some cases + +The specification currently allows presigned, or `same-origin` auth approaches to storage GET URLs. +It does note currently define auth approaches for different origin endpoints where presigned is not used. +This option would explicitly allow implementations to use out-of-band credentials in such cases. + +* Good, because it adds clarity to a currently undefined case +* Good, because it allows common cloud-specific methods such as AWS IAM credentials to be used +* Neutral, because it requires a non-breaking API change + +### Option 5: Allow Service Implementations to solely use out-of-band credentials + +This option would permit implementations to only use out-of-band credentials to be used for storage URLs. + +* Bad, because this would result in all clients requiring to produce implementation specific auth integrations to integrate with Storage Implementations which take this approach +* Bad, because this would compromise interoperability + +### Option 6: Return a list of PUT URLs on the `/flows//storage` endpoint + +This option would see the `/flows//storage` endpoint return a list of PUT URLs for each Object, akin to the `/flows//segments` and `/objects/` endpoints. + +* Good, because PUT and GET URL approaches will be aligned +* Bad, because it would be a breaking change in a core part of the specification +* Bad, because using these multiple URLs for a given Object may result in undefined behaviour +* Bad, because having multiple URLs for a given Object may result in security holes From c45534fea15f7f753f94a9077aa5cefadd6a8228 Mon Sep 17 00:00:00 2001 From: James Sandford Date: Mon, 10 Aug 2026 10:30:51 +0100 Subject: [PATCH 7/7] Mark ADR0054 accepted --- docs/adr/0054-selectable-presigned-storage-urls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/0054-selectable-presigned-storage-urls.md b/docs/adr/0054-selectable-presigned-storage-urls.md index fabe0cf2..d58b1a92 100644 --- a/docs/adr/0054-selectable-presigned-storage-urls.md +++ b/docs/adr/0054-selectable-presigned-storage-urls.md @@ -1,5 +1,5 @@ --- -status: "proposed" +status: "accepted" --- # Support for selectable presigned storage PUT URLs