Add 'chck operation' endpoint

draft-ietf-scitt-scrapi.md

@@ -217,7 +217,7 @@ Payload (in CBOR diagnostic notation)
 
 18([                            / COSE Sign1         /
   h'a1013822',                  / Protected Header   /
-  {},                           / Unprotected Header /
+  {'request_id': '0123abcd'},   / Unprotected Header /
   null,                         / Detached Payload   /
   h'269cd68f4211dffc...0dcb29c' / Signature          /
 ])
@@ -229,6 +229,8 @@ If the `payload` is detached, the Transparency Service depends on the authentica
 If the `payload` is attached, the Transparency Service depends on both the authentication context of the client (if present), and the verification of the Signed Statement in the Registration Policy.
 The details of Registration Policy are out of scope for this document.
 
+The `Unprotected Header` may contain a `request_id` which, if provided, is used for querying long running registrations later.
+
 If registration succeeds the following identifier MAY be used to refer to the Signed Statement that was accepted:
 
 `urn:ietf:params:scitt:signed-statement:sha-256:base64url:5i6UeRzg1...qnGmr1o`
@@ -256,7 +258,7 @@ Payload (in CBOR diagnostic notation)
 
 18([                            / COSE Sign1         /
   h'a1013822',                  / Protected Header   /
-  {},                           / Unprotected Header /
+  {"request_id": "0123abcd"},   / Unprotected Header /
   null,                         / Detached Payload   /
   h'269cd68f4211dffc...0dcb29c' / Signature          /
 ])
@@ -270,25 +272,23 @@ Fresh receipts may be requested through the resource identified in the Location
 ~~~ http-message
 HTTP/1.1 202 Accepted
 
-Location: https://transparency.example/receipts\
-/urn:ietf:params:scitt:signed-statement\
-:sha-256:base64url:5i6UeRzg1...qnGmr1o
+Location: https://transparency.example/operations/0123abcd
 
 Content-Type: application/json
 Retry-After: <seconds>
 
 {
-
-  "identifier": "urn:ietf:params:scitt:receipt\
-:sha-256:base64url:5i6UeRzg1...qnGmr1o",
-
+  "request_id": "0123abcd",
 }
 
 ~~~
 
-The response contains a reference to the receipt which will eventually be available for the Signed Statement.
+The response contains a reference to the running operation which will eventually be available for the Signed Statement.
 
-If 202 is returned, then clients should wait until Registration succeeded or failed by polling the Resolve Receipt endpoint using the identifier returned in the response.
+If the client supplied a `request_id` then the Transparency Service MUST return the same request_id in the response.
+If the client did not supply a `request_id` then the Transparency Service MUST return a locally unique request_id which can be used in subsequent calls to the Check Registration endpoint.
+
+If 202 is returned, then clients should wait until Registration succeeded or failed by polling the Check Operation endpoint using the identifier returned in the response.
 
 #### Status 400 - Invalid Client Request
 
@@ -339,7 +339,82 @@ One of the following errors:
 }
 ~~~
 
-TODO: other error codes
+### Check Registration
+
+Authentication MAY be implemented for this endpoint.
+
+This endpoint is used to check on the progress of a long-running registration.
+
+The following is a non-normative example of a HTTP request the status of a running registration:
+
+Request:
+
+~~~http
+GET /operations/0123abcd, HTTP/1.1
+Host: transparency.example
+Accept: application/json
+~~~
+
+Response:
+
+One of the following:
+
+#### Status 201 - Registration is successful
+
+~~~ http-message
+HTTP/1.1 201 Ok
+
+Location: https://transparency.example/receipts\
+/urn:ietf:params:scitt:signed-statement\
+:sha-256:base64url:5i6UeRzg1...qnGmr1o
+
+Content-Type: application/cose
+
+Payload (in CBOR diagnostic notation)
+
+18([                            / COSE Sign1         /
+  h'a1013822',                  / Protected Header   /
+  {"request_id": "0123abcd"},   / Unprotected Header /
+  null,                         / Detached Payload   /
+  h'269cd68f4211dffc...0dcb29c' / Signature          /
+])
+~~~
+
+The response contains the Receipt for the Signed Statement.
+Fresh receipts may be requested through the resource identified in the Location header.
+
+The Transparency Service MUST maintain a record of every operation until at least one client has fetched the completed receipt.
+
+The Transparency Service MAY maintain a record of the operation beyond the first successful fetch of the completed receipt.
+
+#### Status 202 - Registration is (still) running
+
+~~~ http-message
+HTTP/1.1 202 Accepted
+
+Location: https://transparency.example/operations/0123abcd
+
+Retry-After: <seconds>
+
+~~~
+
+The response contains a reference to the running operation which will eventually be available for the Signed Statement.
+
+If 202 is returned, then clients should wait until Registration succeeded or failed by polling the Check Operation endpoint using the identifier returned in the response.
+
+#### Status 404 - Operation not found
+
+~~~
+{
+  "type": "urn:ietf:params:scitt:error\
+:lro:not-found",
+  "detail": \
+"A registration operation with this identifier was not found."
+}
+~~~
+
+No additional reason codes will be given.
+The identifier may have been valid at a point in time but since redeemed and forgotten; or it may have never existed on this Transparency Service.
 
 ## Optional Endpoints
 
@@ -556,7 +631,7 @@ Content-Type: application/json
 
 #### Status 429
 
-If a client is polling for an in-progress registration too frequently then the Transparency Service MAY, in addition to implementing rate-limiting, return a 429 response:
+If a client is asking for receipts too frequently then the Transparency Service MAY, in addition to implementing rate-limiting, return a 429 response:
 
 ~~~
 HTTP/1.1 429 Too Many Requests