Skip to content

Commit 035194f

Browse files
GsCommandGsCommand
committed
Publish trust-verification CLAS schemas
1 parent b63e9dd commit 035194f

89 files changed

Lines changed: 4195 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎public/schemas/trust-verification/README.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# CLAS Trust Verification v1
2+
3+
## 1. Overview
4+
5+
Trust Verification v1 defines a standards-oriented, machine-readable schema family for trust-related machine actions and decisions. It provides canonical verbs and structured receipts for verification, identity confirmation, permissioning, attestations, approvals, rejections, signatures, and endorsements.
6+
7+
The intent is protocol interoperability: consistent request/receipt structures that can be validated, exchanged, and independently verified across systems.
8+
9+
## 2. Canonical verbs
10+
11+
Trust Verification v1 defines these canonical verbs:
12+
13+
- `verify`
14+
- `authenticate`
15+
- `authorize`
16+
- `attest`
17+
- `sign`
18+
- `permit`
19+
- `grant`
20+
- `approve`
21+
- `reject`
22+
- `endorse`
23+
24+
## 3. Verb definitions
25+
26+
- **verify**: checks whether a subject, proof, receipt, signature, artifact, claim, or workflow result is valid.
27+
- **authenticate**: confirms the identity of an actor, signer, agent, service, key, user, or caller.
28+
- **authorize**: determines whether an actor is allowed to perform an action under a policy or scope.
29+
- **attest**: creates a signed claim about a subject.
30+
- **sign**: applies cryptographic authorship, approval, or intent to a payload.
31+
- **permit**: represents a portable permission artifact.
32+
- **grant**: issues access, authority, rights, or permission to an actor.
33+
- **approve**: records a positive decision on a proposal, transaction, request, deployment, or workflow step.
34+
- **reject**: records a negative decision on a proposal, transaction, request, deployment, or workflow step.
35+
- **endorse**: adds reputation, support, or trust weight to an actor, signer, claim, schema, service, or capability.
36+
37+
## 4. Semantic boundaries
38+
39+
- **verify vs attest**
40+
- `verify` evaluates existing evidence and returns a validity outcome.
41+
- `attest` produces new signed evidence (a claim) about a subject.
42+
43+
- **authenticate vs authorize**
44+
- `authenticate` answers "who is this actor?"
45+
- `authorize` answers "what is this actor allowed to do?"
46+
47+
- **authorize vs approve**
48+
- `authorize` is policy/scope enforcement for allowed actions.
49+
- `approve` is a decision event on a specific request, transaction, or workflow step.
50+
51+
- **grant vs permit**
52+
- `grant` is the issuance action that assigns rights.
53+
- `permit` is the transferable/portable artifact expressing those rights.
54+
55+
- **approve vs reject**
56+
- `approve` records a positive decision.
57+
- `reject` records a negative decision.
58+
59+
- **sign vs attest**
60+
- `sign` binds cryptographic intent/authorship to payload bytes.
61+
- `attest` expresses a semantic claim about a subject and is typically signed.
62+
63+
- **endorse vs certify**
64+
- `endorse` adds support or trust weight without claiming formal institutional certification.
65+
- `certify` is intentionally excluded from v1 because it overlaps with `verify` and `attest` and may imply regulatory or institutional certification semantics.
66+
67+
## 5. Shared proof model
68+
69+
Every receipt references the shared proof schema:
70+
71+
- `../_shared/proof.schema.json`
72+
73+
Shared proof fields (as defined in `_shared/proof.schema.json`):
74+
75+
- `metadata.proof.canonicalization` — canonicalization identifier (const: `json.sorted_keys.v1`)
76+
- `metadata.proof.hash.alg` — hash algorithm (const: `SHA-256`)
77+
- `metadata.proof.hash.value` — lowercase SHA-256 hex digest (`64` hex chars)
78+
- `metadata.proof.signature.alg` — signature algorithm (const: `Ed25519`)
79+
- `metadata.proof.signature.value` — signature value
80+
- `metadata.proof.signature.kid` — key identifier
81+
82+
These fields provide a common cryptographic envelope model across all verb receipts.
83+
84+
## 6. Schema-valid vs cryptographically valid
85+
86+
A receipt can be valid JSON and pass schema validation while still failing cryptographic verification.
87+
88+
Tampered receipts are expected to remain schema-valid but fail signature/hash verification.
89+
90+
Schema conformance and cryptographic integrity are separate checks and must both be evaluated.
91+
92+
## 7. Examples
93+
94+
Each verb's `examples/` folder includes:
95+
96+
- `valid.request.json`: a schema-valid request example for the verb.
97+
- `valid.receipt.json`: a schema-valid receipt example with intact proof fields.
98+
- `tampered.receipt.json`: a schema-valid receipt whose payload/proof relationship has been altered and should fail cryptographic verification.
99+
- `invalid.receipt.json`: a receipt that fails schema validation.
100+
101+
## 8. File convention
102+
103+
Each verb folder contains:
104+
105+
- `<verb>.request.schema.json`
106+
- `<verb>.receipt.schema.json`
107+
- `examples/`

‎public/schemas/trust-verification/_shared/proof.schema.json‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://schemas.commandlayer.org/schemas/v1.0.0/trust/_shared/proof.schema.json",
4+
"title": "CLAS Trust Proof",
5+
"description": "Shared proof envelope for trust verification receipts.",
6+
"type": "object",
7+
"additionalProperties": false,
8+
"required": [
9+
"canonicalization",
10+
"hash",
11+
"signature"
12+
],
13+
"properties": {
14+
"canonicalization": {
15+
"$comment": "erc8211.composable.v1: ERC-8211 composable execution canonicalization recognized. Merkle authorization verification is deferred pending the companion Merkle authorization ERC.",
16+
"enum": [
17+
"json.sorted_keys.v1",
18+
"erc8211.composable.v1"
19+
]
20+
},
21+
"hash": {
22+
"type": "object",
23+
"additionalProperties": false,
24+
"required": [
25+
"alg",
26+
"value"
27+
],
28+
"properties": {
29+
"alg": {
30+
"const": "SHA-256"
31+
},
32+
"value": {
33+
"type": "string",
34+
"pattern": "^[a-fA-F0-9]{64}$"
35+
}
36+
}
37+
},
38+
"signature": {
39+
"oneOf": [
40+
{
41+
"type": "object",
42+
"additionalProperties": false,
43+
"required": [
44+
"alg",
45+
"value",
46+
"kid"
47+
],
48+
"properties": {
49+
"alg": {
50+
"const": "Ed25519"
51+
},
52+
"value": {
53+
"type": "string",
54+
"minLength": 16
55+
},
56+
"kid": {
57+
"type": "string",
58+
"minLength": 1
59+
}
60+
}
61+
},
62+
{
63+
"type": "array",
64+
"minItems": 1,
65+
"items": {
66+
"type": "object",
67+
"additionalProperties": false,
68+
"required": [
69+
"alg",
70+
"value",
71+
"kid",
72+
"role"
73+
],
74+
"properties": {
75+
"alg": {
76+
"const": "Ed25519"
77+
},
78+
"value": {
79+
"type": "string",
80+
"minLength": 16
81+
},
82+
"kid": {
83+
"type": "string",
84+
"minLength": 1
85+
},
86+
"role": {
87+
"type": "string",
88+
"enum": [
89+
"user",
90+
"solver",
91+
"relayer",
92+
"agent",
93+
"runtime",
94+
"verifier"
95+
]
96+
}
97+
}
98+
}
99+
}
100+
]
101+
}
102+
}
103+
}

‎public/schemas/trust-verification/_shared/trace.schema.json‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://schemas.commandlayer.org/schemas/v1.0.0/trust/_shared/trace.schema.json",
4+
"title": "CLAS Trace",
5+
"description": "Shared trace envelope for correlating requests and receipts across agents, hops, workflows, solver fills, and spans.",
6+
"type": "object",
7+
"additionalProperties": false,
8+
"required": [
9+
"trace_id"
10+
],
11+
"properties": {
12+
"trace_id": {
13+
"type": "string",
14+
"maxLength": 128
15+
},
16+
"span_id": {
17+
"type": "string",
18+
"maxLength": 128
19+
},
20+
"parent_span_id": {
21+
"type": "string",
22+
"maxLength": 128
23+
},
24+
"timestamp": {
25+
"type": "string",
26+
"format": "date-time"
27+
},
28+
"tags": {
29+
"type": "object",
30+
"additionalProperties": {
31+
"type": "string",
32+
"maxLength": 512
33+
}
34+
}
35+
}
36+
}

‎public/schemas/trust-verification/approve/approve.mcp.tool.schema.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"name": "clas_trust_approve",
3+
"title": "CLAS Trust Approve",
4+
"description": "Record a positive decision on a proposal, transaction, request, deployment, or workflow step. Successful execution returns a CLAS approve receipt.",
5+
"inputSchema": {
6+
"$ref": "./approve.request.schema.json"
7+
},
8+
"outputSchema": {
9+
"$ref": "./approve.receipt.schema.json",
10+
"description": "CLAS approve receipt returned when approve execution succeeds."
11+
},
12+
"annotations": {
13+
"readOnlyHint": false,
14+
"destructiveHint": false,
15+
"idempotentHint": false,
16+
"openWorldHint": false
17+
}
18+
}

‎public/schemas/trust-verification/approve/approve.openapi.yaml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
openapi: 3.1.0
2+
info:
3+
title: CLAS Trust Verification Approve API
4+
version: 1.0.0
5+
paths:
6+
/v1/trust-verification/approve:
7+
post:
8+
operationId: approveTrustVerificationAction
9+
description: Record a positive decision on a proposal, transaction, request, deployment, or workflow step.
10+
requestBody:
11+
required: true
12+
content:
13+
application/json:
14+
schema:
15+
$ref: ./approve.request.schema.json
16+
responses:
17+
'200':
18+
description: Approve receipt.
19+
content:
20+
application/json:
21+
schema:
22+
$ref: ./approve.receipt.schema.json
23+
'400':
24+
description: Invalid CLAS request.
25+
'401':
26+
description: Unauthorized signer or caller.
27+
'422':
28+
description: Semantic validation failure.

‎public/schemas/trust-verification/approve/approve.receipt.schema.json‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://schemas.commandlayer.org/schemas/v1.0.0/trust/approve/approve.receipt.schema.json",
4+
"title": "CLAS Trust Approve Receipt",
5+
"description": "A signed receipt proving that an approval decision was made.",
6+
"type": "object",
7+
"additionalProperties": false,
8+
"required": [
9+
"version",
10+
"family",
11+
"verb",
12+
"receipt_id",
13+
"request",
14+
"approval",
15+
"ts",
16+
"metadata"
17+
],
18+
"properties": {
19+
"version": {
20+
"const": "1.0.0"
21+
},
22+
"family": {
23+
"const": "trust"
24+
},
25+
"verb": {
26+
"const": "approve"
27+
},
28+
"receipt_id": {
29+
"type": "string",
30+
"minLength": 1
31+
},
32+
"request": {
33+
"$ref": "./approve.request.schema.json"
34+
},
35+
"approval": {
36+
"type": "object",
37+
"additionalProperties": false,
38+
"required": [
39+
"status"
40+
],
41+
"properties": {
42+
"status": {
43+
"type": "string",
44+
"enum": [
45+
"approved",
46+
"denied",
47+
"conditional",
48+
"expired"
49+
]
50+
},
51+
"approval_id": {
52+
"type": "string"
53+
},
54+
"reason": {
55+
"type": "string"
56+
},
57+
"expires_at": {
58+
"type": "string",
59+
"format": "date-time"
60+
}
61+
}
62+
},
63+
"ts": {
64+
"type": "string",
65+
"format": "date-time"
66+
},
67+
"metadata": {
68+
"type": "object",
69+
"additionalProperties": false,
70+
"required": [
71+
"proof"
72+
],
73+
"properties": {
74+
"proof": {
75+
"$ref": "../_shared/proof.schema.json"
76+
},
77+
"trace": {
78+
"$ref": "../_shared/trace.schema.json"
79+
}
80+
}
81+
}
82+
}
83+
}

0 commit comments

Comments
 (0)