Early Review of draft-ietf-scitt-architecture-01
review-ietf-scitt-architecture-01-httpdir-early-miller-2023-04-24-00

Apologies, this a long piece of feedback on draft-ietf-scitt-architecture, I
hope it is useful.

From the perspective of someone who is not an expert in the security field, the
document does a good job of explaining the problem being solved, the use cases
where it is valuable and the mechanics of the process of signing statements and
producing transparent statements. The roles of each of the participants are
clearly explained.

The majority of my feedback is around the specification of the Transparency
Service API in section 8
(https://www.ietf.org/archive/id/draft-ietf-scitt-architecture-01.html#name-transparency-service-api-th).
 From my perspective, the goal of this section should be to ensure
interoperability while imposing the minimum set of constraints on the
implementation of the Transparency service.

Resource Paths
--------------
The current draft defines a fixed set of resource paths relative to a base URL.
 However, BCP 56 https://www.rfc-editor.org/rfc/rfc9205.html#section-4.4.1
recommends providing paths via a discovery document that contains URI Templates
for the required resources exposed by the API.  While the approach proposed by
BCP56 is the most flexible approach, it does make it more challenging to
document and describe the API surface in a way that is familiar to most
developers.  It is worth considering whether the shape of this API surface is
expected to grow over time.  If significant change is expected then the
additional complexity of the discovery document may be warranted.

Base URL
--------
The document should make some statement about how a client might acquire a base
URL.  Is it worth defining a .well-known URL for Transparency Services? Would a
DNS SRV record be appropriate?  Should a link relation be defined so that other
content could point to the Transparency Service via an embedded link?

Standard HTTP behavior
----------------------
The document should avoid restating standard HTTP behavior as described by
RFC9110.  Describing the semantics of 4xx, 5xx, 503 and the retry-after header
is neither necessary nor appropriate.

Error Content
-------------
Use and referencing  of  RFC7807 is good.  However, I don't believe the
document should reiterate how to specify the response Content-Type header. That
content can be in an implementer's guide.

It is not clear to me where a developer might see the "Error code: malformed". 
It looks like some of the error responses have not been updated to be using
RFC7807 syntax.

Response payloads
-----------------
A number of the API responses return a Content-Type: application/json but have
some form of expected response shape.  This kind of tight coupling between
resource paths and expected response shapes is not ideal for internet standards
as it is not resilient to change and does not enable clients to negotiate for
content, or for intermediaries to have visibility into the content.

One suggestion would be to use the document to register a media type such as
application/scitt-message+json and then define the media type to have structure
such as this structure described in CDDL:

scitt-message= {
    ? registration : registration
    ? operation : operation
}
registration = {
    entryUrl: string
}
operation = {
    operationUrl: string
    status: running / succeeded / failed
    ? error: error
}
error = {
    type: string
    detail: string
}

This allows the media type in the response content-type to communicate the
semantics of the response message.  The structure is flexible enough to return
both the registration information and/or the state of the running operation. 
This structure could easily be extended to add support for other message kinds
needed by the transparency service.

By providing a entryUrl property in the registration, the client does not need
to have knowledge of how to construct valid URLs to access the registration
entry.  Additionally it avoids the need to return the Location header in the
200 response from the Operation resource.  Location headers in 200 responses
are not defined.

Additionally the semantics of Location header are not defined for 202 responses
in RFC 9110.  As the 202 response does return the representation of the
operation resource, it would be appropriate to return a Content-Location header
that contains the Operation URL to provide the client a place to continue to
poll for status.

Here is a suggestion of how these calls might look using the suggestions made:

## Create an entry
POST <baseUrl>/entries
Content-Type: application/cose

[SCITT COSE_Sign1 message]

201 Created
Content-Type: application/scitt-message+json
Location: <baseUrl>/entries/<id>

{
    "registration": {
        "entryUrl": "<baseUrl>/entries/<id>"
    }
}

### Create an entry with a 202 response
POST <baseUrl>/entries
Content-Type: application/cose

[SCITT COSE_Sign1 message]

202 Accepted
Content-Type: application/scitt-message+json
Content-Location: <baseUrl>/operations/<id>

{
    "operation": {
        "operationUrl": "<baseUrl>/operations/<id>",
        "status": "running"
    }
}

### Poll an operation that has not finished
GET <baseUrl>/operation/<id>
Content-Type: application/cose

[SCITT COSE_Sign1 message]

200 Ok
Content-Type: application/scitt-message+json

{
    "operation": {
        "operationUrl": "<baseUrl>/operations/<id>",
        "status": "running"
    }
}

### Poll an operation that has finished
GET <baseUrl>/operation/<id>
Content-Type: application/cose

[SCITT COSE_Sign1 message]

200 Ok
Content-Type: application/scitt-message+json

{
    "operation": {
        "operationUrl": "<baseUrl>/operations/<id>",
        "status": "succeeded"
    },
    "registration": {
        "entryUrl": "<baseUrl>/entries/<id>"
    }
}

Overall, this specification looks like it has been well thought out and is
solving a valuable problem.  Hopefully, my suggestions around the Transparent
API Services will provide some value.