Developers

Create, export and independently verify JEP Core 0.7 events locally.

Create and verify locally

Git and Python 3.10 or later. Installation needs internet access; the example runs locally without an account or API service.

git clone --branch v2.1.8 --depth 1 https://github.com/hjs-spec/jep-agent-sdk.git
cd jep-agent-sdk
python3 -m venv .venv
. .venv/bin/activate
python -m pip install jep-agent-sdk==2.1.8 jep-core-conformance==0.7.7
python examples/local_roundtrip.py create ./local-evidence
python examples/local_roundtrip.py verify ./local-evidence
jep-validate validate ./local-evidence/event.json --keys ./local-evidence/keys.json

Result

Both verification commands should report status: valid and checks.cryptographic: pass, with the same event_hash.

The local-evidence directory contains event.json, public-key.pem and keys.json.

  • Use a new working directory and output path; the example does not overwrite existing evidence.
  • The demo uses a temporary key. Use an independently trusted key to verify a real actor.

A valid signature shows that the declared key signed the event. It does not prove that the signer is a trusted real-world identity.

Next: Record your own calls

Connect over HTTP

Start the reference API locally, then create and verify events through a client. The API holds the signing key; clients send requests.

Start the API and run an HTTP exampleQuickstart 0.7.2 · API 0.8.7

Language clients

Event format and validation details

Event structure

Placeholders show where each member goes. Generate a real signed event with the local example above.

Structural sketch — not a verifiable sample
{
  "jep": "1",
  "id": "<event identifier>",
  "verb": "J",
  "who": "<declared subject>",
  "when": <declared time>,
  "what": { <verb-specific content> },
  "aud": "<optional audience>",
  "ref": "<digest string or typed reference object>",
  "sig": <signature container, produced by a signer>
}

Standard top-level members

jepREQUIRED
Wire-format version. Current value is the string "1".
idREQUIRED
Event identifier. Event Identity is (who, id).
verbREQUIRED
Event verb: "J", "D", "T" or "V".
whoREQUIRED
Subject declared by the event. The field alone does not prove real-world identity.
whenREQUIRED
Time declared by the subject. Not a trusted timestamp on its own.
whatREQUIRED
Verb-specific content.
audOPTIONAL
Intended audience or validation context.
refCONDITIONAL
A digest string or a typed reference object — not an array.
extOPTIONAL
Extension object.
ext_critCONDITIONAL
Identifiers of extensions that must be understood.
sigREQUIRED
Signature container. Covers the exact signed artifact identified by Event Hash.

jep, id, verb, who, when, what and sig are unconditionally required. aud, ref, ext and ext_crit are conditional or optional depending on the event and extensions.

Signature model

JEP Core defines a generic signature container; concrete algorithms come from a signature baseline or profile. The current tooling baseline is JCS canonicalization with Ed25519 detached JWS. No other algorithm is claimed as supported by these tools.

Independent validation checks

A verifier reports each check it performed separately from the overall valid / invalid / indeterminate status. A check that was not performed is never shown as pass.

Profile and companion checks are only performed by implementations that support those profiles; they are not guaranteed by every Core implementation.

For error codes and result formats, see the validator documentation for the version you run.

Resources