@whooshbang/contracts 1.0.0-rc.13

package/schemas/webhooks/webhook-delivery-case-v1.schema.json

@@ -0,0 +1,167 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://whooshbang.flowxo.com/schemas/webhooks/webhook-delivery-case-v1.schema.json",
+  "x-contract-version": "1.0.0-rc.13",
+  "title": "WebhookDeliveryCaseSetV1",
+  "description": "Deterministic customer webhook response classification, Retry-After, and delivery-bound cases.",
+  "type": "object",
+  "required": ["schema", "cases"],
+  "properties": {
+    "schema": {
+      "const": "whooshbang.webhook-delivery-cases.v1"
+    },
+    "cases": {
+      "type": "array",
+      "minItems": 20,
+      "maxItems": 64,
+      "x-unique-property": "id",
+      "items": {
+        "$ref": "#/$defs/DeliveryCase"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "NetworkFailure": {
+      "type": "object",
+      "required": ["kind"],
+      "properties": {
+        "kind": {
+          "const": "network_failure"
+        }
+      },
+      "additionalProperties": false
+    },
+    "HttpOutcome": {
+      "type": "object",
+      "required": ["kind", "status"],
+      "properties": {
+        "kind": {
+          "const": "http"
+        },
+        "status": {
+          "type": "integer",
+          "minimum": 100,
+          "maximum": 599
+        },
+        "retry_after": {
+          "type": "string",
+          "maxLength": 128
+        }
+      },
+      "additionalProperties": false
+    },
+    "AcceptedExpectation": {
+      "type": "object",
+      "required": ["action", "reason"],
+      "properties": {
+        "action": {
+          "const": "accepted"
+        },
+        "reason": {
+          "const": "http_2xx"
+        }
+      },
+      "additionalProperties": false
+    },
+    "TerminalExpectation": {
+      "type": "object",
+      "required": ["action", "reason"],
+      "properties": {
+        "action": {
+          "const": "terminal"
+        },
+        "reason": {
+          "type": "string",
+          "enum": [
+            "attempt_limit_exhausted",
+            "delivery_window_exhausted",
+            "http_terminal",
+            "redirect_not_followed",
+            "unexpected_http_status"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "RetryExpectation": {
+      "type": "object",
+      "required": ["action", "reason", "latest_retry_at_epoch_seconds"],
+      "properties": {
+        "action": {
+          "const": "retry"
+        },
+        "reason": {
+          "type": "string",
+          "enum": ["network_failure", "retryable_http_status"]
+        },
+        "latest_retry_at_epoch_seconds": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "retry_after_seconds": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 86400
+        }
+      },
+      "additionalProperties": false
+    },
+    "DeliveryCase": {
+      "type": "object",
+      "required": [
+        "id",
+        "attempt",
+        "first_attempt_at_epoch_seconds",
+        "now_epoch_seconds",
+        "outcome",
+        "expected"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[a-z][a-z0-9_-]*$"
+        },
+        "attempt": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 8
+        },
+        "first_attempt_at_epoch_seconds": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "now_epoch_seconds": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "outcome": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/NetworkFailure"
+            },
+            {
+              "$ref": "#/$defs/HttpOutcome"
+            }
+          ]
+        },
+        "expected": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/AcceptedExpectation"
+            },
+            {
+              "$ref": "#/$defs/TerminalExpectation"
+            },
+            {
+              "$ref": "#/$defs/RetryExpectation"
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/webhooks/webhook-signing-vector-v1.schema.json

@@ -0,0 +1,197 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://whooshbang.flowxo.com/schemas/webhooks/webhook-signing-vector-v1.schema.json",
+  "x-contract-version": "1.0.0-rc.13",
+  "title": "WebhookSigningVectorSetV1",
+  "description": "Language-neutral deterministic Standard Webhooks V1 verification vectors. All key material is public synthetic test data and must never be used outside fixtures.",
+  "type": "object",
+  "required": ["schema", "synthetic_verification_keys", "raw_bodies", "cases"],
+  "properties": {
+    "schema": {
+      "const": "whooshbang.webhook-signing-vectors.v1"
+    },
+    "synthetic_verification_keys": {
+      "type": "object",
+      "minProperties": 3,
+      "maxProperties": 8,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9_]*$"
+      },
+      "additionalProperties": {
+        "type": "string",
+        "pattern": "^whsec_(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$"
+      }
+    },
+    "raw_bodies": {
+      "type": "object",
+      "minProperties": 2,
+      "maxProperties": 8,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9_]*$"
+      },
+      "additionalProperties": {
+        "type": "string",
+        "minLength": 2,
+        "maxLength": 16384
+      }
+    },
+    "cases": {
+      "type": "array",
+      "minItems": 16,
+      "maxItems": 64,
+      "x-unique-property": "id",
+      "items": {
+        "$ref": "#/$defs/VerificationCase"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "Header": {
+      "type": "object",
+      "required": ["name", "value"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "value": {
+          "type": "string",
+          "maxLength": 1024
+        }
+      },
+      "additionalProperties": false
+    },
+    "VerifiedExpectation": {
+      "type": "object",
+      "required": ["verified", "event_id", "timestamp", "attempt"],
+      "properties": {
+        "verified": {
+          "const": true
+        },
+        "event_id": {
+          "type": "string",
+          "minLength": 8,
+          "maxLength": 128
+        },
+        "timestamp": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "attempt": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 8
+        }
+      },
+      "additionalProperties": false
+    },
+    "RejectedExpectation": {
+      "type": "object",
+      "required": ["verified", "reason"],
+      "properties": {
+        "verified": {
+          "const": false
+        },
+        "reason": {
+          "type": "string",
+          "enum": [
+            "crypto_unavailable",
+            "duplicate_header",
+            "duplicate_secret",
+            "duplicate_signature",
+            "invalid_body",
+            "invalid_clock",
+            "invalid_secret",
+            "invalid_tolerance",
+            "malformed_attempt",
+            "malformed_header",
+            "malformed_signature",
+            "malformed_timestamp",
+            "malformed_webhook_id",
+            "missing_header",
+            "signature_mismatch",
+            "timestamp_outside_tolerance",
+            "too_many_secrets",
+            "too_many_signatures",
+            "unsupported_signature_version"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "VerificationCase": {
+      "type": "object",
+      "required": [
+        "id",
+        "raw_body",
+        "headers",
+        "trusted_keys",
+        "now_seconds",
+        "tolerance_seconds",
+        "expected"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[a-z][a-z0-9_-]*$"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 500
+        },
+        "raw_body": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]*$"
+        },
+        "headers": {
+          "type": "array",
+          "minItems": 0,
+          "maxItems": 8,
+          "items": {
+            "$ref": "#/$defs/Header"
+          }
+        },
+        "trusted_keys": {
+          "type": "array",
+          "minItems": 0,
+          "maxItems": 3,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*$"
+          }
+        },
+        "now_seconds": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "tolerance_seconds": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 300
+        },
+        "duplicate_of": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[a-z][a-z0-9_-]*$"
+        },
+        "expected": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/VerifiedExpectation"
+            },
+            {
+              "$ref": "#/$defs/RejectedExpectation"
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}