Update SigningConfig to specify API version and validity periods

In order to faciliate clients gracefully handling breaking API
changes, the SigningConfig will now include API versions for each
of the service URLs so that clients can determine what services
they are compatible with. Additionally, we've included validity periods
which will be used to faciliate Rekor log sharding, when we spin up new
log shards and distribute new key material.

Fixes #474

Signed-off-by: Hayden B <8418760+haydentherapper@users.noreply.github.com>

wip

Author: Hayden-IO

gen/jsonschema/schemas/ClientTrustConfig.schema.json

@@ -186,33 +186,97 @@
             "title": "Certificate Authority",
             "description": "CertificateAuthority enlists the information required to identify which CA to use and perform signature verification."
         },
-        "dev.sigstore.trustroot.v1.SigningConfig": {
+        "dev.sigstore.trustroot.v1.Service": {
             "properties": {
-                "mediaType": {
+                "url": {
                     "type": "string",
-                    "description": "MUST be application/vnd.dev.sigstore.signingconfig.v0.1+json"
+                    "description": "URL of the service. MUST include scheme and authority. MAY include path."
+                },
+                "majorApiVersion": {
+                    "type": "integer",
+                    "description": "Specifies the major API version. A value of 0 represents a service that has not yet been released."
                 },
-                "caUrl": {
+                "validFor": {
+                    "$ref": "#/definitions/dev.sigstore.common.v1.TimeRange",
+                    "additionalProperties": false,
+                    "description": "Validity period of a service. A service that has only a start date SHOULD be considered the most recent instance of that service, but the client MUST NOT assume there is only one valid instance. The TimeRange MUST be considered valid *inclusive* of the endpoints."
+                }
+            },
+            "additionalProperties": false,
+            "type": "object",
+            "title": "Service",
+            "description": "Service represents an instance of a service that is a part of Sigstore infrastructure. Clients MUST use the API version hint to determine the service with the highest API version that the client is compatible with. Clients MUST also only connect to services within the specified validity period and that has the newest validity start date."
+        },
+        "dev.sigstore.trustroot.v1.ServiceConfiguration": {
+            "properties": {
+                "selector": {
+                    "enum": [
+                        "SERVICE_SELECTOR_UNDEFINED",
+                        "ALL",
+                        "ANY",
+                        "EXACT"
+                    ],
                     "type": "string",
-                    "description": "A URL to a Fulcio-compatible CA, capable of receiving Certificate Signing Requests (CSRs) and responding with issued certificates. This URL **MUST** be the \"base\" URL for the CA, which clients should construct an appropriate CSR endpoint on top of. For example, if `ca_url` is `https://example.com/ca`, then the client **MAY** construct the CSR endpoint as `https://example.com/ca/api/v2/signingCert`."
+                    "title": "Service Selector",
+                    "description": "ServiceSelector specifies how a client should select a set of Services to connect to. A client SHOULD throw an error if the value is SERVICE_SELECTOR_UNDEFINED."
                 },
-                "oidcUrl": {
+                "count": {
+                    "type": "integer",
+                    "description": "count specifies the number of Services the client should use. Only used when selector is set to EXACT, and count MUST be greater than 0. count MUST be less than or equal to the number of Services."
+                }
+            },
+            "additionalProperties": false,
+            "type": "object",
+            "title": "Service Configuration",
+            "description": "ServiceConfiguration specifies how a client should select a set of Services to connect to, along with a count when a specific number of Services is requested."
+        },
+        "dev.sigstore.trustroot.v1.SigningConfig": {
+            "properties": {
+                "mediaType": {
                     "type": "string",
-                    "description": "A URL to an OpenID Connect identity provider. This URL **MUST** be the \"base\" URL for the OIDC IdP, which clients should perform well-known OpenID Connect discovery against."
+                    "description": "MUST be application/vnd.dev.sigstore.signingconfig.v0.2+json Clients MAY choose to also support application/vnd.dev.sigstore.signingconfig.v0.1+json"
+                },
+                "caUrls": {
+                    "items": {
+                        "$ref": "#/definitions/dev.sigstore.trustroot.v1.Service"
+                    },
+                    "additionalProperties": false,
+                    "type": "array",
+                    "description": "URLs to Fulcio-compatible CAs, capable of receiving Certificate Signing Requests (CSRs) and responding with issued certificates. These URLs MUST be the \"base\" URL for the CAs, which clients should construct an appropriate CSR endpoint on top of. For example, if a CA URL is `https://example.com/ca`, then the client **MAY** construct the CSR endpoint as `https://example.com/ca/api/v2/signingCert`. Clients MUST select only one Service with the highest API version that the client is compatible with, that is within its validity period, and has the newest validity start date. Client SHOULD select the first Service that meets this requirement. All listed Services SHOULD be sorted by the `valid_for` window in descending order, with the newest instance first."
                 },
-                "tlogUrls": {
+                "oidcUrls": {
                     "items": {
-                        "type": "string"
+                        "$ref": "#/definitions/dev.sigstore.trustroot.v1.Service"
                     },
+                    "additionalProperties": false,
                     "type": "array",
-                    "description": "One or more URLs to Rekor-compatible transparency log. Each URL **MUST** be the \"base\" URL for the transparency log, which clients should construct appropriate API endpoints on top of."
+                    "description": "URLs to OpenID Connect identity providers. These URLs MUST be the \"base\" URLs for the OIDC IdPs, which clients should perform well-known OpenID Connect discovery against. Clients MUST select only one Service with the highest API version that the client is compatible with, that is within its validity period, and has the newest validity start date. Client SHOULD select the first Service that meets this requirement. All listed Services SHOULD be sorted by the `valid_for` window in descending order, with the newest instance first."
+                },
+                "rekorTlogUrls": {
+                    "items": {
+                        "$ref": "#/definitions/dev.sigstore.trustroot.v1.Service"
+                    },
+                    "additionalProperties": false,
+                    "type": "array",
+                    "description": "URLs to Rekor transparency logs. These URL MUST be the \"base\" URLs for the transparency logs, which clients should construct appropriate API endpoints on top of. Clients MUST select Services with the highest API version that the client is compatible with, that are within its validity period, and have the newest validity start dates. All listed Services SHOULD be sorted by the `valid_for` window in descending order, with the newest instance first. Clients MUST select Services based on the selector value of `rekor_tlog_config`."
+                },
+                "rekorTlogConfig": {
+                    "$ref": "#/definitions/dev.sigstore.trustroot.v1.ServiceConfiguration",
+                    "additionalProperties": false,
+                    "description": "Specifies how a client should select the set of Rekor transparency logs to write to."
                 },
                 "tsaUrls": {
                     "items": {
-                        "type": "string"
+                        "$ref": "#/definitions/dev.sigstore.trustroot.v1.Service"
                     },
+                    "additionalProperties": false,
                     "type": "array",
-                    "description": "One ore more URLs to RFC 3161 Time Stamping Authority (TSA). Each URL **MUST** be the **full** URL for the TSA, meaning that it should be suitable for submitting Time Stamp Requests (TSRs) to via HTTP, per RFC 3161."
+                    "description": "URLs to RFC 3161 Time Stamping Authorities (TSA). These URLs MUST be the **full** URL for the TSA, meaning that it should be suitable for submitting Time Stamp Requests (TSRs) to via HTTP, per RFC 3161. Clients MUST select Services with the highest API version that the client is compatible with, that are within its validity period, and have the newest validity start dates. All listed Services SHOULD be sorted by the `valid_for` window in descending order, with the newest instance first. Clients MUST select Services based on the selector value of `tsa_config`."
+                },
+                "tsaConfig": {
+                    "$ref": "#/definitions/dev.sigstore.trustroot.v1.ServiceConfiguration",
+                    "additionalProperties": false,
+                    "description": "Specifies how a client should select the set of TSAs to request signed timestamps from."
                 }
             },
             "additionalProperties": false,

gen/jsonschema/schemas/Service.schema.json

@@ -0,0 +1,50 @@
+{
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "$ref": "#/definitions/Service",
+    "definitions": {
+        "Service": {
+            "properties": {
+                "url": {
+                    "type": "string",
+                    "description": "URL of the service. MUST include scheme and authority. MAY include path."
+                },
+                "majorApiVersion": {
+                    "type": "integer",
+                    "description": "Specifies the major API version. A value of 0 represents a service that has not yet been released."
+                },
+                "validFor": {
+                    "$ref": "#/definitions/dev.sigstore.common.v1.TimeRange",
+                    "additionalProperties": false,
+                    "description": "Validity period of a service. A service that has only a start date SHOULD be considered the most recent instance of that service, but the client MUST NOT assume there is only one valid instance. The TimeRange MUST be considered valid *inclusive* of the endpoints."
+                }
+            },
+            "additionalProperties": false,
+            "type": "object",
+            "title": "Service",
+            "description": "Service represents an instance of a service that is a part of Sigstore infrastructure. Clients MUST use the API version hint to determine the service with the highest API version that the client is compatible with. Clients MUST also only connect to services within the specified validity period and that has the newest validity start date."
+        },
+        "dev.sigstore.common.v1.TimeRange": {
+            "properties": {
+                "start": {
+                    "type": "string",
+                    "format": "date-time"
+                },
+                "end": {
+                    "type": "string",
+                    "format": "date-time"
+                }
+            },
+            "additionalProperties": false,
+            "type": "object",
+            "oneOf": [
+                {
+                    "required": [
+                        "end"
+                    ]
+                }
+            ],
+            "title": "Time Range",
+            "description": "The time range is closed and includes both the start and end times, (i.e., [start, end]). End is optional to be able to capture a period that has started but has no known end."
+        }
+    }
+}

gen/jsonschema/schemas/ServiceConfiguration.schema.json

@@ -0,0 +1,29 @@
+{
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "$ref": "#/definitions/ServiceConfiguration",
+    "definitions": {
+        "ServiceConfiguration": {
+            "properties": {
+                "selector": {
+                    "enum": [
+                        "SERVICE_SELECTOR_UNDEFINED",
+                        "ALL",
+                        "ANY",
+                        "EXACT"
+                    ],
+                    "type": "string",
+                    "title": "Service Selector",
+                    "description": "ServiceSelector specifies how a client should select a set of Services to connect to. A client SHOULD throw an error if the value is SERVICE_SELECTOR_UNDEFINED."
+                },
+                "count": {
+                    "type": "integer",
+                    "description": "count specifies the number of Services the client should use. Only used when selector is set to EXACT, and count MUST be greater than 0. count MUST be less than or equal to the number of Services."
+                }
+            },
+            "additionalProperties": false,
+            "type": "object",
+            "title": "Service Configuration",
+            "description": "ServiceConfiguration specifies how a client should select a set of Services to connect to, along with a count when a specific number of Services is requested."
+        }
+    }
+}