standards

Standards

Rules for the Verae MCP timestamping server.

Protocol

This process is an MCP server (Model Context Protocol). Clients are assistants and inspectors that speak MCP. It is not a REST product API and not a browser session by itself.

Hash only

Callers send a SHA-256 digest: 64 lowercase hex characters. A sha256: prefix is stripped.
The server does not read files, does not accept document bytes, and does not hash content.
Empty input has the well-known digest e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855. Callers may stamp that digest. The server does not invent it from a missing file.

Scopes

Scope	Where the receipt lives
`local`	JSON file, default `~/.verae/mcp-timestamp-local.json`
`shared`	Same file. There is no separate shared store in this process
`global`	`POST https://api.veraetime.net/api/timestamp` with `wait=true`

want_scope=global on verify asks VeraeTime. A local receipt cannot satisfy global.

Global history

hash_report reads the local file only. VeraeTime is not queried for a digest history. A global stamp can verify by certificate id and still be absent from hash_report. An empty list means “not in the local file,” not “VeraeTime has no record.”

Credentials

Token: VERAE_GLOBAL_TOKEN, else access_token / id_token / auth_token in ~/.verae/auth.properties (VERAE_AUTH_PROPERTIES overrides the path).
Do not commit tokens. .env is gitignored.
The local receipt file is mode 0600 after each save.

NATS

NatsLedger is optional and is not the default. It uses core NATS request/reply:

verae.ts.request
verae.ts.verify
verae.hash.report

Job-complete and receipt notifications stay ephemeral core NATS (verae.ts.completed, verae.ts.receipt). This server does not put those events on JetStream.

Transports

`VERAE_MCP_TRANSPORT`	Bind
unset or `stdio`	Parent process stdin/stdout
`streamable-http`	`VERAE_MCP_HOST` (default `127.0.0.1`) and `VERAE_MCP_PORT` (default `8000`), path `/mcp`

Leave the HTTP bind on loopback unless a reverse proxy terminates TLS and authentication in front of it. Do not publish the VeraeTime bearer token on an open internet listener.

Errors

Invalid digests and unknown scopes raise ToolError with the ValueError text. HTTP failures from VeraeTime surface as global timestamp HTTP <status>.