Add ExternalTrustSignalProvider adapter contract

contracts/external-trust-signal-provider.schema.json

@@ -0,0 +1,346 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:srcos:agent-machine:schema:external-trust-signal-provider:v0.1.0",
+  "title": "ExternalTrustSignalProvider",
+  "description": "Secret-free adapter request/response contract for optional non-authoritative external identity, reputation, certificate-tier, counterparty, and registry lookup signals used as Agent Registry verifier inputs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "specVersion",
+    "id",
+    "kind",
+    "request",
+    "response",
+    "receiptSafety",
+    "observedAt"
+  ],
+  "$defs": {
+    "signalType": {
+      "type": "string",
+      "enum": [
+        "agent-identity",
+        "cert-tier",
+        "reputation-score",
+        "counterparty-check",
+        "registry-lookup",
+        "other"
+      ]
+    },
+    "sha256Digest": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "freshness": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "maxAgeSeconds",
+        "observedAgeSeconds",
+        "fresh"
+      ],
+      "properties": {
+        "maxAgeSeconds": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "observedAgeSeconds": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "fresh": {
+          "type": "boolean"
+        }
+      }
+    },
+    "signature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "required",
+        "observed",
+        "signatureRef",
+        "signerRef"
+      ],
+      "properties": {
+        "required": {
+          "type": "boolean"
+        },
+        "observed": {
+          "type": "boolean"
+        },
+        "signatureRef": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "signerRef": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "externalTrustSignal": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "providerRef",
+        "signalType",
+        "signalRef",
+        "signalDigest",
+        "verifiedAt",
+        "freshness",
+        "signature",
+        "authority",
+        "failureReason"
+      ],
+      "properties": {
+        "providerRef": {
+          "type": "string"
+        },
+        "signalType": {
+          "$ref": "#/$defs/signalType"
+        },
+        "signalRef": {
+          "type": "string"
+        },
+        "signalDigest": {
+          "$ref": "#/$defs/sha256Digest"
+        },
+        "verifiedAt": {
+          "type": "string"
+        },
+        "freshness": {
+          "$ref": "#/$defs/freshness"
+        },
+        "signature": {
+          "$ref": "#/$defs/signature"
+        },
+        "authority": {
+          "type": "string",
+          "const": "non-authoritative-verifier-input"
+        },
+        "failureReason": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "notes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "properties": {
+    "specVersion": {
+      "type": "string",
+      "const": "0.1.0"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:agent-machine:external-trust-signal-provider:[a-z0-9][a-z0-9-]*$"
+    },
+    "kind": {
+      "type": "string",
+      "const": "ExternalTrustSignalProvider"
+    },
+    "request": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "requestId",
+        "providerRef",
+        "agentPodId",
+        "requestedAgentIdentityRef",
+        "sessionRef",
+        "workroomRef",
+        "topicRef",
+        "requestedSignalTypes",
+        "verificationFreshnessSeconds",
+        "requestedExpiresAt",
+        "signatureRequired"
+      ],
+      "properties": {
+        "requestId": {
+          "type": "string"
+        },
+        "providerRef": {
+          "type": "string"
+        },
+        "agentPodId": {
+          "type": "string",
+          "pattern": "^urn:srcos:agent-machine:agent-pod:[a-z0-9][a-z0-9-]*$"
+        },
+        "requestedAgentIdentityRef": {
+          "type": "string"
+        },
+        "sessionRef": {
+          "type": "string"
+        },
+        "workroomRef": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "topicRef": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "requestedSignalTypes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/signalType"
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "verificationFreshnessSeconds": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "requestedExpiresAt": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "signatureRequired": {
+          "type": "boolean"
+        }
+      }
+    },
+    "response": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "usableForGrantResolution",
+        "providerRef",
+        "authority",
+        "verifiedAt",
+        "freshness",
+        "signals",
+        "failureReason"
+      ],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "available",
+            "unavailable",
+            "stale",
+            "malformed",
+            "unsigned",
+            "denied",
+            "error"
+          ]
+        },
+        "usableForGrantResolution": {
+          "type": "boolean"
+        },
+        "providerRef": {
+          "type": "string"
+        },
+        "authority": {
+          "type": "string",
+          "const": "non-authoritative-verifier-input"
+        },
+        "verifiedAt": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "freshness": {
+          "$ref": "#/$defs/freshness"
+        },
+        "signals": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/externalTrustSignal"
+          }
+        },
+        "failureReason": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "receiptSafety": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "includeRawContent",
+        "rawPromptContentIncluded",
+        "rawKvCacheContentIncluded",
+        "secretValuesIncluded",
+        "privateMemoryIncluded",
+        "apiKeysIncluded",
+        "walletPrivateKeysIncluded",
+        "rawCredentialsIncluded",
+        "rawUserDataIncluded"
+      ],
+      "properties": {
+        "includeRawContent": {
+          "type": "boolean",
+          "const": false
+        },
+        "rawPromptContentIncluded": {
+          "type": "boolean",
+          "const": false
+        },
+        "rawKvCacheContentIncluded": {
+          "type": "boolean",
+          "const": false
+        },
+        "secretValuesIncluded": {
+          "type": "boolean",
+          "const": false
+        },
+        "privateMemoryIncluded": {
+          "type": "boolean",
+          "const": false
+        },
+        "apiKeysIncluded": {
+          "type": "boolean",
+          "const": false
+        },
+        "walletPrivateKeysIncluded": {
+          "type": "boolean",
+          "const": false
+        },
+        "rawCredentialsIncluded": {
+          "type": "boolean",
+          "const": false
+        },
+        "rawUserDataIncluded": {
+          "type": "boolean",
+          "const": false
+        }
+      }
+    },
+    "observedAt": {
+      "type": "string"
+    },
+    "labels": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    }
+  }
+}

docs/architecture/agent-registry-grants.md

@@ -10,7 +10,7 @@ This grant is a local SourceOS control-plane artifact. It may consume external i
 AgentPod
   -> Policy Fabric admission
   -> Agent Registry grant request
-  -> optional external verifier inputs
+  -> optional ExternalTrustSignalProvider verifier inputs
   -> local grant resolution
   -> ActivationDecision
   -> runtime placement or fail-closed
@@ -56,9 +56,11 @@ Allowed scope must be no broader than the requested scope. Denied scope is expli
 
 ## External trust signals
 
-External systems can be useful for agent identity verification, reputation, counterparty checks, and certificate-tier claims. They are not the Agent Registry.
+External systems can be useful for agent identity verification, reputation, counterparty checks, registry lookup, and certificate-tier claims. They are not the Agent Registry.
 
-When used, external trust signals must be recorded under `grant.externalTrustSignals` with:
+`ExternalTrustSignalProvider` artifacts represent those adapter results. A usable result can be considered by the local Agent Registry grant resolver only when it is fresh, signed when signatures are required, scoped to the requested provider and signal types, and marked with `authority: non-authoritative-verifier-input`.
+
+When used inside an `AgentRegistryGrant`, external trust signals must be recorded under `grant.externalTrustSignals` with:
 
 - the provider reference;
 - the signal type;
@@ -67,7 +69,7 @@ When used, external trust signals must be recorded under `grant.externalTrustSig
 - verification time;
 - `authority: non-authoritative-verifier-input`.
 
-This keeps PCH/ERC-8004-style identity, reputation, and certificate-tier checks pluggable without making any external gateway the SourceOS root of trust.
+This keeps PCH/ERC-8004-style identity, reputation, registry lookup, and certificate-tier checks pluggable without making any external gateway the SourceOS root of trust.
 
 ## Fail-closed rules
 
@@ -79,10 +81,11 @@ Activation fails closed when:
 - the requested provider is not present in allowed provider scope;
 - required activation tools are absent from allowed tool scope;
 - the grant is missing a revocation hook;
-- the grant payload includes secrets, raw prompts, raw KV-cache contents, or private memory contents.
+- required external trust signals are unavailable, stale, malformed, unsigned when signatures are required, or authority-elevated;
+- the grant or external trust payload includes secrets, raw prompts, raw KV-cache contents, private memory contents, API keys, private wallet keys, raw credentials, or raw user data.
 
 ## Relation to receipts
 
-`DeploymentReceipt` proves deterministic derivation. `PolicyAdmission` proves policy admission. `AgentRegistryGrant` proves identity/session/tool/provider/storage authorization. `ActivationDecision` combines those inputs and either permits scoped activation or records fail-closed reasons.
+`DeploymentReceipt` proves deterministic derivation. `PolicyAdmission` proves policy admission. `ExternalTrustSignalProvider` proves optional verifier-input posture. `AgentRegistryGrant` proves identity/session/tool/provider/storage authorization. `ActivationDecision` combines those inputs and either permits scoped activation or records fail-closed reasons.
 
 None of these artifacts should include raw prompt content, KV-cache contents, secret values, private memory, or raw user data.