Add certs, JWS, payload schemas

Following [RFC 5], add new JSON schemas for a `certs` property containing JWS [JSON Serialization], supporting both the general and flattened syntaxes. The schemas are: * `certs.schema.json`: One or more certifications, with the `pgxn` property required. * `jws.schema.json`: JWS general and flattened [JSON Serialization] * `jws-header.schema.json`: JWS headers * `jwk.schema.json`: [RFC 7517] JSON Web Key (JWK) format, required by the `jwk` property of `jws-header.schema.json` * `payload.schema.json`: The PGXN release payload Include tests for each of these schemas, and fix comments for existing schema tests. [RFC 5]: pgxn/rfcs#5 [JSON Serialization]: https://datatracker.ietf.org/doc/html/rfc7515#section-7 [RFC 7517]: https://datatracker.ietf.org/doc/html/rfc7517
pgxn · Oct 8, 2024 · 0773ad7 · 0773ad7
1 parent a5dbedd
commit 0773ad7
Show file tree

Hide file tree

Showing 6 changed files with 1,675 additions and 28 deletions.
diff --git a/schema/v2/certs.schema.json b/schema/v2/certs.schema.json
@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://pgxn.org/meta/v2/certs.schema.json",
+  "title": "Certifications",
+  "description": "One or more cryptographic signatures or certifications that attest to the authenticity or other characteristics of a distribution release.",
+  "type": "object",
+  "properties": {
+    "pgxn": { "$ref": "jws.schema.json" }
+  },
+  "patternProperties": { "^[xX]_.": { "description": "Custom key" } },
+  "additionalProperties": false,
+  "required": ["pgxn"]
+}
diff --git a/schema/v2/jwk.schema.json b/schema/v2/jwk.schema.json
@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://pgxn.org/meta/v2/jwk.schema.json",
+  "title": "JSON Web Key",
+  "description": "[RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517) JSON Web Key (JWK) format. Supports both the general and flattened syntaxes.",
+  "type": "object",
+  "properties": {
+    "kty": {
+      "type": "string",
+      "description": "Key Type: identifies the cryptographic algorithm family used with the key, such as “RSA”  or “EC”."
+    },
+    "use": {
+      "type": "string",
+      "description": "Public Key Use: identifies the intended use of the public key — encrypting data (“enc”) or verifying the signature on data (“sig”)."
+    },
+    "key_ops": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" },
+      "description": "Key Operations: identifies the operation(s) for which the key is intended to be used, and intended for use cases in which public, private, or symmetric keys may be present."
+    },
+    "alg": {
+      "type": "string",
+      "description": "Algorithm: identifies the algorithm intended for use with the key."
+    },
+    "kid": {
+      "type": "string",
+      "description": "Key ID: used to match a specific key."
+    },
+    "x5u": {
+      "type": "string",
+      "format": "uri",
+      "description": "X.509 URL: a URI  that refers to a resource for an X.509 public key certificate or  certificate chain"
+    },
+    "x5c": {
+      "type": "array",
+      "description": "X.509 Certificate Chain: contains a chain of one or more PKIX certificates",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9+/]*={0,2}$",
+        "description": "Base 64-encoded DER PKIX certificate value."
+      }
+    },
+    "x5t": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9-_]{12,}$",
+      "description": "X.509 Certificate SHA-1 Thumbprint: Base 64 URL-encoded SHA-1 thumbprint (a.k.a. digest) of the DER encoding of an X.509 certificate."
+    },
+    "x5t#S256": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9-_]{12,}$",
+      "description": "X.509 Certificate SHA-256 Thumbprint: Base 64 URL-encoded SHA-256 thumbprint (a.k.a. digest) of the DER encoding of an X.509 certificate."
+    }
+  },
+  "required": ["kty"],
+  "examples": [
+    {
+      "kty": "EC",
+      "crv": "P-256",
+      "x": "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
+      "y": "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
+      "use": "enc",
+      "kid": "1"
+    },
+    {
+      "kty": "RSA",
+      "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
+      "e": "AQAB",
+      "alg": "RS256",
+      "kid": "2011-04-29"
+    }
+  ]
+}
diff --git a/schema/v2/jws-header.schema.json b/schema/v2/jws-header.schema.json
@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://pgxn.org/meta/v2/jws-header.schema.json",
+  "title": "JWS JOSE Header",
+  "description": "[RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515) JSON Web Signature (JWS) [Header](https://datatracker.ietf.org/doc/html/rfc7515#section-4) format, describing the digital signature or MAC applied to the JWS Protected Header and the JWS Payload and optionally additional properties of the JWS.",
+  "type": "object",
+  "properties": {
+    "alg": {
+      "type": "string",
+      "description": "Algorithm: identifies the cryptographic algorithm used to secure the JWS."
+    },
+    "jku": {
+      "type": "string",
+      "format": "uri",
+      "description": "JWK Set URL: a URI that refers to a resource for a set of JSON-encoded public keys, one of which corresponds to the key used to digitally sign the JWS."
+    },
+    "jwk": {
+      "$ref": "jwk.schema.json",
+      "description": "JSON Web Key: the public key that corresponds to the key used to digitally sign the JWS, formatted as a JSON Web Key (JWK)."
+    },
+    "kid": {
+      "type": "string",
+      "description": "Key ID: a hint indicating which key was used to secure the JWS."
+    },
+    "x5u": {
+      "type": "string",
+      "format": "uri",
+      "description": "X.509 URL: a URI that refers to a resource for the X.509 public key certificate or certificate chain corresponding to the key used to digitally sign the JWS."
+    },
+    "x5c": {
+      "type": "array",
+      "description": "X.509 Certificate Chain: the X.509 public key certificate or certificate chain [RFC5280] corresponding to the key used to digitally sign the JWS.",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9+/]*={0,2}$",
+        "description": "Base 64-encoded DER PKIX certificate value."
+      }
+    },
+    "x5t": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9-_]{12,}$",
+      "description": "X.509 Certificate SHA-1 Thumbprint: Base 64 URL-encoded SHA-1 thumbprint (a.k.a. digest) of the DER encoding of the X.509 certificate corresponding to the key used to digitally sign the JWS."
+    },
+    "x5t#S256": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9-_]{12,}$",
+      "description": "X.509 Certificate SHA-256 Thumbprint: Base 64 URL-encoded SHA-256 thumbprint (a.k.a. digest) of the DER encoding of the X.509 certificate corresponding to the key used to digitally sign the JWS."
+    },
+    "typ": {
+      "type": "string",
+      "description": "Type: used by JWS applications to declare the media type of this complete JWS."
+    },
+    "cty": {
+      "type": "string",
+      "description": "Content Type: used by JWS applications to declare the media type [IANA.MediaTypes](https://datatracker.ietf.org/doc/html/rfc7515#ref-IANA.MediaTypes) of the secured content (the payload)."
+    }
+  },
+  "minProperties": 1,
+  "examples": [{ "kid": "2010-12-29" }, { "typ": "JWT", "alg": "HS256" }]
+}
diff --git a/schema/v2/jws.schema.json b/schema/v2/jws.schema.json
@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://pgxn.org/meta/v2/jws.schema.json",
+  "title": "JWS JSON Serialization",
+  "description": "[RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515) JSON Web Signature (JWS) [JSON Serialization](https://datatracker.ietf.org/doc/html/rfc7515#section-7.2). Supports both the general and flattened syntaxes.",
+  "type": "object",
+  "oneOf": [
+    {
+      "$comment": "[General JWS JSON Serialization Syntax](https://datatracker.ietf.org/doc/html/rfc7515#section-7.2.1)",
+      "properties": {
+        "payload": { "$ref": "#/$defs/payload" },
+        "signatures": {
+          "type": "array",
+          "description": "Encoded JWS Signature values",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "properties": {
+              "protected": { "$ref": "#/$defs/protected" },
+              "header": { "$ref": "jws-header.schema.json" },
+              "signature": { "$ref": "#/$defs/signature" }
+            },
+            "required": ["signature"]
+          }
+        }
+      },
+      "required": ["payload", "signatures"],
+      "additionalProperties": true
+    },
+    {
+      "$comment": "[Flattened JWS JSON Serialization Syntax](https://datatracker.ietf.org/doc/html/rfc7515#section-7.2.2)",
+      "properties": {
+        "payload": { "$ref": "#/$defs/payload" },
+        "protected": { "$ref": "#/$defs/protected" },
+        "header": { "$ref": "jws-header.schema.json" },
+        "signature": { "$ref": "#/$defs/signature" }
+      },
+      "required": ["payload", "signature"],
+      "additionalProperties": true
+    }
+  ],
+  "$comment": "Additional members can be present in both the JSON objects defined above; if not understood by implementations encountering them, they MUST be ignored.",
+  "examples": [
+    {
+      "protected": "eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9",
+      "payload": "eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ",
+      "signature": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
+    },
+    {
+      "protected": "eyJhbGciOiJSUzI1NiJ9",
+      "payload": "eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ",
+      "signature": "cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7AAuHIm4Bh-r7t1dnZcAcQjbKBYNX4BAynRFdiuBLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqvhJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrBp0igcN_IoypGlUPQGe77Rw"
+    },
+    {
+      "payload": "eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ",
+      "signatures": [
+        {
+          "protected": "eyJhbGciOiJSUzI1NiJ9",
+          "header": {
+            "kid": "2010-12-29"
+          },
+          "signature": "cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqvhJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrBp0igcN_IoypGlUPQGe77Rw"
+        },
+        {
+          "protected": "eyJhbGciOiJFUzI1NiJ9",
+          "header": {
+            "kid": "e9bc097a-ce51-4036-9562-d2ade882db0d"
+          },
+          "signature": "DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSApmWQxfKTUJqPP3-Kg6NU1Q"
+        }
+      ]
+    }
+  ],
+  "$defs": {
+    "signature": {
+      "type": "string",
+      "description": "Base 64 URL-encoded signature.",
+      "pattern": "^[A-Za-z0-9-_]{32,}$"
+    },
+    "protected": {
+      "type": "string",
+      "description": "Base 64 URL-encoded protected header.",
+      "pattern": "^[A-Za-z0-9-_]{12,}$"
+    },
+    "payload": {
+      "type": "string",
+      "description": "Base 64 URL-encoded data to be secured.",
+      "pattern": "^[A-Za-z0-9-_]{12,}$"
+    }
+  }
+}
diff --git a/schema/v2/payload.schema.json b/schema/v2/payload.schema.json
@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://pgxn.org/meta/v2/payload.schema.json",
+  "title": "PGXN Release Payload",
+  "description": "JSON Web Signature release payload populated by PGXN.",
+  "type": "object",
+  "properties": {
+    "user": {
+      "$ref": "term.schema.json",
+      "description": "The PGXN username for the user who released the distribution to PGXN.",
+      "examples": ["theory", "keithf4"]
+    },
+    "date": {
+      "type": "string",
+      "format": "date-time",
+      "description": "The release timestamp.",
+      "examples": ["2024-09-12T19:56:49Z"]
+    },
+    "uri": {
+      "type": "string",
+      "format": "uri-reference",
+      "pattern": "^dist/",
+      "description": "Path to the release file relative to a PGXN base URL.",
+      "examples": [
+        "dist/pair/0.1.7/pair-0.1.7.zip",
+        "dist/plv8/3.2.3/plv8-3.2.3.zip"
+      ]
+    },
+    "digests": {
+      "$ref": "digests.schema.json"
+    }
+  },
+  "required": ["user", "date", "uri", "digests"],
+  "additionalProperties": false,
+  "examples": [
+    {
+      "user": "theory",
+      "date": "2024-07-20T20:34:34Z",
+      "uri": "dist/semver/0.40.0/semver-0.40.0.zip",
+      "digests": {
+        "sha1": "fe8c013f991b5f537c39fb0c0b04bc955457675a"
+      }
+    },
+    {
+      "user": "theory",
+      "date": "2024-09-13T17:32:55Z",
+      "uri": "dist/pair/0.1.7/pair-0.1.7.zip",
+      "digests": {
+        "sha256": "257b71aa57a28d62ddbb301333b3521ea3dc56f17551fa0e4516b03998abb089",
+        "sha512": "b353b5a82b3b54e95f4a2859e7a2bd0648abcb35a7c3612b126c2c75438fc2f8e8ee1f19e61f30fa54d7bb64bcf217ed1264722b497bcb613f82d78751515b67"
+      }
+    }
+  ]
+}