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. [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 · 31b68cb · 31b68cb
1 parent a5dbedd
commit 31b68cb
Show file tree

Hide file tree

Showing 6 changed files with 1,684 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"
+ }
+ }
+ ]
+}