thumbgate 1.34.3 → 1.37.1

package/config/progressive/05-strict-optional.json

@@ -0,0 +1,11 @@
+{
+  "phase": 5,
+  "name": "strict-optional",
+  "detectEnabled": true,
+  "strict": true,
+  "commands": [
+    "THUMBGATE_STRICT_ENFORCEMENT=1"
+  ],
+  "verify": "Only after phases 1–4. Matching learned rules can hard-deny.",
+  "hiddenMetric": "Strict is opt-in. Secret-exfil floors already deny without it."
+}

package/config/progressive/README.md

@@ -0,0 +1,15 @@
+# Progressive wiring (Frigate-style)
+
+Prove the pipe before you turn detection on.
+
+| Phase | File | Enable matching? | Verify |
+| --- | --- | --- | --- |
+| 1 | `01-wire-only.json` | no | `npx thumbgate doctor` |
+| 2 | `02-dashboard-empty-ok.json` | no | dashboard loads, empty OK |
+| 3 | `03-one-lesson.json` | no | `npx thumbgate stats` |
+| 4 | `04-warn-fires.json` | yes, warn | hook log / gate-stats |
+| 5 | `05-strict-optional.json` | yes, strict | only after 1–4 |
+
+Hidden metric: if nothing fires, check **hook install**, not rule count.
+
+Live guide: `/guides/progressive-wiring`

package/config/schemas/broker-execution-receipt.schema.json

@@ -0,0 +1,139 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://thumbgate.ai/schemas/broker-execution-receipt.schema.json",
+  "title": "ThumbGate Broker-Signed Execution Receipt",
+  "description": "Broker-signed record that a credential-holding broker (outside the agent trust boundary) authorized or denied a side-effecting action. Agents cannot mint valid signatures. A receipt is not independent world-state proof and does not mean a public listing is invocable.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "receiptId",
+    "principal",
+    "target",
+    "decision",
+    "idempotencyKey",
+    "issuedAt",
+    "broker",
+    "payloadHash",
+    "signature",
+    "receiptHash"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "broker-execution-receipt-v1"
+    },
+    "receiptId": {
+      "type": "string",
+      "minLength": 8,
+      "maxLength": 120
+    },
+    "principal": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "kind": {
+          "type": "string",
+          "enum": ["agent", "user", "service", "system"]
+        }
+      }
+    },
+    "target": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "action"],
+      "properties": {
+        "provider": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120
+        },
+        "resource": {
+          "type": "string",
+          "maxLength": 500
+        },
+        "action": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120
+        }
+      }
+    },
+    "decision": {
+      "type": "string",
+      "enum": ["allow", "execute", "deny"]
+    },
+    "idempotencyKey": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 300
+    },
+    "providerEventId": {
+      "type": ["string", "null"],
+      "maxLength": 300
+    },
+    "issuedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "broker": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "kind": {
+          "type": "string",
+          "const": "broker"
+        }
+      }
+    },
+    "payloadHash": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "previousReceiptHash": {
+      "type": ["string", "null"],
+      "pattern": "^([a-f0-9]{64})?$"
+    },
+    "signature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["alg", "publicKeyId", "value"],
+      "properties": {
+        "alg": {
+          "type": "string",
+          "const": "ed25519"
+        },
+        "publicKeyId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "value": {
+          "type": "string",
+          "minLength": 16,
+          "maxLength": 500
+        }
+      }
+    },
+    "receiptHash": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  }
+}

package/config/schemas/provider-execution-attestation-v1.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/IgorGanapolsky/ThumbGate/blob/main/config/schemas/provider-execution-attestation-v1.schema.json",
+  "title": "ThumbGate Provider Execution Attestation v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "attestationId", "provider", "credentialHolder", "thumbgate", "providerEvidence", "reconciliationPolicy", "outcome", "issuedAt", "nonce", "signature"],
+  "properties": {
+    "schemaVersion": { "const": "thumbgate-provider-execution-attestation-v1" },
+    "attestationId": { "type": "string", "minLength": 1, "maxLength": 200 },
+    "provider": {
+      "type": "object", "additionalProperties": false, "required": ["id", "accountId"],
+      "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 120 }, "accountId": { "type": "string", "minLength": 1, "maxLength": 200 } }
+    },
+    "credentialHolder": {
+      "type": "object", "additionalProperties": false, "required": ["id", "kind"],
+      "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "enum": ["broker", "vault", "gateway"] } }
+    },
+    "thumbgate": {
+      "type": "object", "additionalProperties": false, "required": ["receiptId", "actionHash"],
+      "properties": { "receiptId": { "type": "string", "minLength": 1, "maxLength": 200 }, "actionHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }
+    },
+    "providerEvidence": {
+      "type": "object", "additionalProperties": false,
+      "required": ["auditSource", "observedAt", "windowStartedAt", "windowClosesAt", "observedLagMs"],
+      "properties": {
+        "eventId": { "type": ["string", "null"], "maxLength": 300 },
+        "auditSource": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "observedAt": { "type": "string", "format": "date-time" },
+        "windowStartedAt": { "type": "string", "format": "date-time" },
+        "windowClosesAt": { "type": "string", "format": "date-time" },
+        "observedLagMs": { "type": "integer", "minimum": 0 },
+        "rawDigest": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
+        "locator": { "type": ["string", "null"], "maxLength": 500 }
+      }
+    },
+    "reconciliationPolicy": {
+      "type": "object", "additionalProperties": false, "required": ["provider", "maxWindowMs", "declaredWindowMs"],
+      "properties": {
+        "provider": { "type": "string", "minLength": 1, "maxLength": 120 },
+        "maxWindowMs": { "type": "integer", "minimum": 1 },
+        "declaredWindowMs": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "outcome": { "enum": ["matched", "mismatched", "not-yet-visible", "absent-after-window"] },
+    "issuedAt": { "type": "string", "format": "date-time" },
+    "nonce": { "type": "string", "minLength": 16, "maxLength": 200 },
+    "signature": {
+      "type": "object", "additionalProperties": false, "required": ["alg", "keyId", "payloadHash", "value"],
+      "properties": {
+        "alg": { "const": "Ed25519" },
+        "keyId": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "payloadHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "value": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/conformance/provider-attestation/vectors.json

@@ -0,0 +1,320 @@
+{
+  "specVersion": "1.0.0",
+  "canonicalization": "RFC 8785 JCS",
+  "signatureInput": "lowercase hex SHA-256 of JCS payload, encoded as UTF-8",
+  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAs837FHU3G9hjEQkcBguaGpWKQYBK+hrd3zrqylXGyHE=\n-----END PUBLIC KEY-----\n",
+  "vectors": [
+    {
+      "id": "matched-valid-jcs",
+      "expectedValid": true,
+      "attestation": {
+        "schemaVersion": "thumbgate-provider-execution-attestation-v1",
+        "attestationId": "att-vector-001",
+        "provider": {
+          "id": "example-cloud",
+          "accountId": "acct-test-001"
+        },
+        "credentialHolder": {
+          "id": "example-vault",
+          "kind": "vault"
+        },
+        "thumbgate": {
+          "receiptId": "receipt-test-001",
+          "actionHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+        },
+        "providerEvidence": {
+          "eventId": "evt-test-001",
+          "auditSource": "example-cloud-audit",
+          "observedAt": "2026-08-14T12:00:30.000Z",
+          "windowStartedAt": "2026-08-14T12:00:00.000Z",
+          "windowClosesAt": "2026-08-14T12:05:00.000Z",
+          "observedLagMs": 30000,
+          "rawDigest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+          "locator": "audit://example-cloud/evt-test-001"
+        },
+        "reconciliationPolicy": {
+          "provider": "example-cloud",
+          "maxWindowMs": 600000,
+          "declaredWindowMs": 300000
+        },
+        "outcome": "matched",
+        "issuedAt": "2026-08-14T12:00:31.000Z",
+        "nonce": "0000000000000001",
+        "signature": {
+          "alg": "Ed25519",
+          "keyId": "test-key-rfc8785-v1",
+          "payloadHash": "f9fc1a6d56d73dad634082b2617c9f9aac0e74101e5af11edc0e05e3668635c5",
+          "value": "946QZB9xWxZVaFezqXDLLsYVzUjrmrbBDSvKhWbOhZ/7dmTe7StDvqODDIf6YFrIdDtTN4n09HeKm432Mti4AQ=="
+        }
+      },
+      "expectedCanonicalPayload": "{\"attestationId\":\"att-vector-001\",\"credentialHolder\":{\"id\":\"example-vault\",\"kind\":\"vault\"},\"issuedAt\":\"2026-08-14T12:00:31.000Z\",\"nonce\":\"0000000000000001\",\"outcome\":\"matched\",\"provider\":{\"accountId\":\"acct-test-001\",\"id\":\"example-cloud\"},\"providerEvidence\":{\"auditSource\":\"example-cloud-audit\",\"eventId\":\"evt-test-001\",\"locator\":\"audit://example-cloud/evt-test-001\",\"observedAt\":\"2026-08-14T12:00:30.000Z\",\"observedLagMs\":30000,\"rawDigest\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"windowClosesAt\":\"2026-08-14T12:05:00.000Z\",\"windowStartedAt\":\"2026-08-14T12:00:00.000Z\"},\"reconciliationPolicy\":{\"declaredWindowMs\":300000,\"maxWindowMs\":600000,\"provider\":\"example-cloud\"},\"schemaVersion\":\"thumbgate-provider-execution-attestation-v1\",\"thumbgate\":{\"actionHash\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"receiptId\":\"receipt-test-001\"}}"
+    },
+    {
+      "id": "mismatched-valid",
+      "expectedValid": true,
+      "attestation": {
+        "schemaVersion": "thumbgate-provider-execution-attestation-v1",
+        "attestationId": "att-vector-002",
+        "provider": {
+          "id": "example-cloud",
+          "accountId": "acct-test-001"
+        },
+        "credentialHolder": {
+          "id": "example-vault",
+          "kind": "vault"
+        },
+        "thumbgate": {
+          "receiptId": "receipt-test-001",
+          "actionHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+        },
+        "providerEvidence": {
+          "eventId": "evt-test-001",
+          "auditSource": "example-cloud-audit",
+          "observedAt": "2026-08-14T12:00:30.000Z",
+          "windowStartedAt": "2026-08-14T12:00:00.000Z",
+          "windowClosesAt": "2026-08-14T12:05:00.000Z",
+          "observedLagMs": 30000,
+          "rawDigest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+          "locator": "audit://example-cloud/evt-test-001"
+        },
+        "reconciliationPolicy": {
+          "provider": "example-cloud",
+          "maxWindowMs": 600000,
+          "declaredWindowMs": 300000
+        },
+        "outcome": "mismatched",
+        "issuedAt": "2026-08-14T12:00:31.000Z",
+        "nonce": "0000000000000001",
+        "signature": {
+          "alg": "Ed25519",
+          "keyId": "test-key-rfc8785-v1",
+          "payloadHash": "0ba89f00278add0b907f7f7696342d5fda4a081cefe81c00cb6a9de43e04f3ae",
+          "value": "Jv52aWKWrXBquOhRpo2Qo0NkAveaT5HUHscc6UheMB59OaG7uqUun6KwTTpF3NY8+MCP5WCC4MTjPzCKF7LxDw=="
+        }
+      }
+    },
+    {
+      "id": "not-yet-visible-valid",
+      "expectedValid": true,
+      "attestation": {
+        "schemaVersion": "thumbgate-provider-execution-attestation-v1",
+        "attestationId": "att-vector-003",
+        "provider": {
+          "id": "example-cloud",
+          "accountId": "acct-test-001"
+        },
+        "credentialHolder": {
+          "id": "example-vault",
+          "kind": "vault"
+        },
+        "thumbgate": {
+          "receiptId": "receipt-test-001",
+          "actionHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+        },
+        "providerEvidence": {
+          "eventId": null,
+          "auditSource": "example-cloud-audit",
+          "observedAt": "2026-08-14T12:00:30.000Z",
+          "windowStartedAt": "2026-08-14T12:00:00.000Z",
+          "windowClosesAt": "2026-08-14T12:05:00.000Z",
+          "observedLagMs": 30000,
+          "rawDigest": null,
+          "locator": null
+        },
+        "reconciliationPolicy": {
+          "provider": "example-cloud",
+          "maxWindowMs": 600000,
+          "declaredWindowMs": 300000
+        },
+        "outcome": "not-yet-visible",
+        "issuedAt": "2026-08-14T12:00:31.000Z",
+        "nonce": "0000000000000001",
+        "signature": {
+          "alg": "Ed25519",
+          "keyId": "test-key-rfc8785-v1",
+          "payloadHash": "a14b992953fcdbb7daf30bc71e8e1cc206d49194509fb697af82819b27deb765",
+          "value": "RpPkTXdpYl3XmQUJiXcYD8xJEwZePx6Hm/5tE87xqszytJUWR9IJCwBcPv8/PWFGgkYL7nxgGDxOMCJv1PRpDQ=="
+        }
+      }
+    },
+    {
+      "id": "absent-after-window-valid",
+      "expectedValid": true,
+      "attestation": {
+        "schemaVersion": "thumbgate-provider-execution-attestation-v1",
+        "attestationId": "att-vector-004",
+        "provider": {
+          "id": "example-cloud",
+          "accountId": "acct-test-001"
+        },
+        "credentialHolder": {
+          "id": "example-vault",
+          "kind": "vault"
+        },
+        "thumbgate": {
+          "receiptId": "receipt-test-001",
+          "actionHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+        },
+        "providerEvidence": {
+          "eventId": null,
+          "auditSource": "example-cloud-audit",
+          "observedAt": "2026-08-14T12:05:00.000Z",
+          "windowStartedAt": "2026-08-14T12:00:00.000Z",
+          "windowClosesAt": "2026-08-14T12:05:00.000Z",
+          "observedLagMs": 300000,
+          "rawDigest": null,
+          "locator": null
+        },
+        "reconciliationPolicy": {
+          "provider": "example-cloud",
+          "maxWindowMs": 600000,
+          "declaredWindowMs": 300000
+        },
+        "outcome": "absent-after-window",
+        "issuedAt": "2026-08-14T12:05:01.000Z",
+        "nonce": "0000000000000001",
+        "signature": {
+          "alg": "Ed25519",
+          "keyId": "test-key-rfc8785-v1",
+          "payloadHash": "736085db205e7eb81e27688d80ceeece194fae9c6ff5f6bf0ed52a3d8f225b83",
+          "value": "s3Cd1lAFaMHi2UM6kqkjx0VbgyZOCKg8k4NwG8UEVrGk+5yoChnYrkbJ/bsKsVlp4NvuF3Pv8d0WzVN13RuQAw=="
+        }
+      }
+    },
+    {
+      "id": "absence-before-window-invalid",
+      "expectedValid": false,
+      "attestation": {
+        "schemaVersion": "thumbgate-provider-execution-attestation-v1",
+        "attestationId": "att-vector-005",
+        "provider": {
+          "id": "example-cloud",
+          "accountId": "acct-test-001"
+        },
+        "credentialHolder": {
+          "id": "example-vault",
+          "kind": "vault"
+        },
+        "thumbgate": {
+          "receiptId": "receipt-test-001",
+          "actionHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+        },
+        "providerEvidence": {
+          "eventId": null,
+          "auditSource": "example-cloud-audit",
+          "observedAt": "2026-08-14T12:00:30.000Z",
+          "windowStartedAt": "2026-08-14T12:00:00.000Z",
+          "windowClosesAt": "2026-08-14T12:05:00.000Z",
+          "observedLagMs": 30000,
+          "rawDigest": null,
+          "locator": null
+        },
+        "reconciliationPolicy": {
+          "provider": "example-cloud",
+          "maxWindowMs": 600000,
+          "declaredWindowMs": 300000
+        },
+        "outcome": "absent-after-window",
+        "issuedAt": "2026-08-14T12:00:31.000Z",
+        "nonce": "0000000000000001",
+        "signature": {
+          "alg": "Ed25519",
+          "keyId": "test-key-rfc8785-v1",
+          "payloadHash": "ac34469e12a33c57e7cd66b91f324b64cd88475214da4efffb6ee107ad52b50f",
+          "value": "tGbY53yETzbFO/bpihhDSJxBNVHzSfSKuUvtwm2SiYa1a1AlepM/8Csq8dEbJA+UXiMbwWTguj4zRLxHzqrsBQ=="
+        }
+      },
+      "expectedError": "absence_claimed_before_window_closed"
+    },
+    {
+      "id": "not-yet-visible-after-window-invalid",
+      "expectedValid": false,
+      "attestation": {
+        "schemaVersion": "thumbgate-provider-execution-attestation-v1",
+        "attestationId": "att-vector-006",
+        "provider": {
+          "id": "example-cloud",
+          "accountId": "acct-test-001"
+        },
+        "credentialHolder": {
+          "id": "example-vault",
+          "kind": "vault"
+        },
+        "thumbgate": {
+          "receiptId": "receipt-test-001",
+          "actionHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+        },
+        "providerEvidence": {
+          "eventId": null,
+          "auditSource": "example-cloud-audit",
+          "observedAt": "2026-08-14T12:05:00.000Z",
+          "windowStartedAt": "2026-08-14T12:00:00.000Z",
+          "windowClosesAt": "2026-08-14T12:05:00.000Z",
+          "observedLagMs": 30000,
+          "rawDigest": null,
+          "locator": null
+        },
+        "reconciliationPolicy": {
+          "provider": "example-cloud",
+          "maxWindowMs": 600000,
+          "declaredWindowMs": 300000
+        },
+        "outcome": "not-yet-visible",
+        "issuedAt": "2026-08-14T12:00:31.000Z",
+        "nonce": "0000000000000001",
+        "signature": {
+          "alg": "Ed25519",
+          "keyId": "test-key-rfc8785-v1",
+          "payloadHash": "d2b8324ac3f43d82e1814ce70955d18d972c40eb1c64e6dbce0226be0dce03c0",
+          "value": "C0jnPNMZgjh9AW7LzR+VsfGSapj+OHp5n39JkX7+z0yThyo2S2Qlq2S/mHq2MFQZ/e4hW5NewYdONR5Hto5FDw=="
+        }
+      },
+      "expectedError": "not_yet_visible_after_window"
+    },
+    {
+      "id": "holder-window-widening-invalid",
+      "expectedValid": false,
+      "attestation": {
+        "schemaVersion": "thumbgate-provider-execution-attestation-v1",
+        "attestationId": "att-vector-007",
+        "provider": {
+          "id": "example-cloud",
+          "accountId": "acct-test-001"
+        },
+        "credentialHolder": {
+          "id": "example-vault",
+          "kind": "vault"
+        },
+        "thumbgate": {
+          "receiptId": "receipt-test-001",
+          "actionHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+        },
+        "providerEvidence": {
+          "eventId": "evt-test-001",
+          "auditSource": "example-cloud-audit",
+          "observedAt": "2026-08-14T12:00:30.000Z",
+          "windowStartedAt": "2026-08-14T12:00:00.000Z",
+          "windowClosesAt": "2026-08-14T12:15:00.000Z",
+          "observedLagMs": 30000,
+          "rawDigest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+          "locator": "audit://example-cloud/evt-test-001"
+        },
+        "reconciliationPolicy": {
+          "provider": "example-cloud",
+          "maxWindowMs": 600000,
+          "declaredWindowMs": 900000
+        },
+        "outcome": "matched",
+        "issuedAt": "2026-08-14T12:00:31.000Z",
+        "nonce": "0000000000000001",
+        "signature": {
+          "alg": "Ed25519",
+          "keyId": "test-key-rfc8785-v1",
+          "payloadHash": "20286e82435d12e3aa7905c2e051eb37bfef92a2c485161e6d82560260063e12",
+          "value": "18zFQgQG8gUZdN+6M7ciAs/6iHZyuG0gO/H8tjbJK6q5aT1EEMNzVK3WUOIfempgPDbJq5TdOuDegP0J3gTSBg=="
+        }
+      },
+      "expectedError": "holder_window_exceeds_gate_maximum"
+    }
+  ]
+}

package/docs/specs/provider-execution-attestation-v1.md

@@ -0,0 +1,69 @@
+# ThumbGate Provider Execution Attestation v1
+
+**Status:** Open provider-neutral specification  
+**Schema:** [`config/schemas/provider-execution-attestation-v1.schema.json`](../../config/schemas/provider-execution-attestation-v1.schema.json)  
+**Normative vectors:** [`conformance/provider-attestation/vectors.json`](../../conformance/provider-attestation/vectors.json)  
+**Verifier:** [`scripts/provider-attestation-conformance.js`](../../scripts/provider-attestation-conformance.js)  
+**Quality evidence:** [`VERIFICATION_EVIDENCE.md`](../../VERIFICATION_EVIDENCE.md)
+
+
+## Permanent public links
+
+| Artifact | URL |
+|---|---|
+| Spec (this document) | https://github.com/IgorGanapolsky/ThumbGate/blob/main/docs/specs/provider-execution-attestation-v1.md |
+| JSON Schema | https://raw.githubusercontent.com/IgorGanapolsky/ThumbGate/main/config/schemas/provider-execution-attestation-v1.schema.json |
+| Normative vectors | https://raw.githubusercontent.com/IgorGanapolsky/ThumbGate/main/conformance/provider-attestation/vectors.json |
+| Verifier | https://github.com/IgorGanapolsky/ThumbGate/blob/main/scripts/provider-attestation-conformance.js |
+
+Evaluate locally after cloning:
+
+```bash
+npm run prove:provider-attestation
+# or
+node scripts/provider-attestation-conformance.js
+```
+
+## Purpose
+
+This contract lets a credential-holding broker, vault, or gateway attest to the result of a provider-side action without giving the AI agent provider credentials. ThumbGate binds the attestation to its pre-action execution receipt and independently verifies the holder's evidence.
+
+The schema and normative synthetic fixtures are free to evaluate. Provider-specific mapping, live audit-surface calibration, adapter implementation, and conformance certification are commercial integration work.
+
+## Canonicalization and signature
+
+1. Remove the top-level `signature` member.
+2. Serialize the remaining payload with JSON Canonicalization Scheme, **RFC 8785 JCS**.
+3. Compute lowercase hexadecimal SHA-256 over the UTF-8 canonical bytes.
+4. Set `signature.payloadHash` to that digest.
+5. Sign the UTF-8 bytes of the lowercase digest with Ed25519.
+6. Store the Base64 signature in `signature.value`.
+
+These steps are normative. Implementations that sign ordinary `JSON.stringify` output are non-conformant.
+
+## Reconciliation outcomes
+
+| Outcome | Meaning | Timing rule |
+|---|---|---|
+| `matched` | Provider evidence agrees with the expected action | Requires `eventId` |
+| `mismatched` | Provider evidence exists but disagrees | Requires `eventId` |
+| `not-yet-visible` | Event is not visible and the window remains open | Retryable only while `observedAt < windowClosesAt` |
+| `absent-after-window` | Event remained absent through the full window | Valid only when `observedAt >= windowClosesAt` |
+
+Absence is not mismatch. Eventual consistency must not become a false deny before the provider window closes.
+
+## Window ownership
+
+ThumbGate owns `maxWindowMs` per provider. The credential holder declares the applied `declaredWindowMs`, which must not exceed the maximum, and reports `observedLagMs`. A holder cannot widen the gate's policy until an event appears.
+
+## Running the normative suite
+
+```bash
+node scripts/provider-attestation-conformance.js
+```
+
+A conforming implementation must produce the expected verdict for every vector and must reproduce `expectedCanonicalPayload` where present.
+
+## Live canaries
+
+Live-provider canaries should measure real audit lag and validate provider adapters. They are deliberately non-normative because provider availability, credentials, and eventual-consistency behavior cannot make the portable conformance suite deterministic.

package/openapi/openapi.yaml

@@ -173,6 +173,9 @@ components:
           enum: [agent, service, human]
         displayName:
           type: string
+        role:
+          type: string
+          enum: [admin, reviewer]
     HumanEscalationRequest:
       type: object
       additionalProperties: false
@@ -200,6 +203,12 @@ components:
           minimum: 1
         idempotencyKey:
           type: string
+        approvalContextDigest:
+          type: string
+          pattern: '^[a-fA-F0-9]{64}$'
+        requiredReviewerRole:
+          type: string
+          enum: [admin]
     HumanEscalationDecision:
       type: object
       additionalProperties: false
@@ -1946,6 +1955,12 @@ paths:
                       - rules
                       - tools
                       - provenance
+                strategy: { type: string, enum: [summarize-then-expand] }
+                contextEnvelope:
+                  type: object
+                  additionalProperties: false
+                  required: [goal, businessData, examples, procedures, constraints, rubric]
+                  properties: { goal: { type: string, minLength: 1 }, businessData: &contextList { type: array, minItems: 1, items: { type: string, minLength: 1 } }, examples: *contextList, procedures: *contextList, constraints: *contextList, rubric: *contextList }
       responses:
         '200':
           description: Context pack created