Watch

George Lambert 1ca834900e feat: site WIP — downloads, explorer, hasher, TestFlight enroll

Commit restored mcp.verae.ai site pages (app, register, macos, windows,
explorer), hasher/download artifacts, index/sample/hasher updates, ledger
and global_client improvements, NATS stamp helper, and TestFlight enroll
service. Ignore debug-trace/ and editor backups. Standard Readme for
download and enroll docs.

2026-09-29 11:18:59 -04:00

2.9 KiB

Raw Blame History

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 with want_scope=global calls VeraeTime GET /api/hash/{digest} (Carfax). Without that scope it reads the local file and also merges central history when available. An empty list means no receipts were found for that digest in the queried ledgers.

Credentials

Token: VERAE_GLOBAL_TOKEN, else access_token / id_token / auth_token in ~/.verae/auth.properties (VERAE_AUTH_PROPERTIES overrides the path).
login writes that file (mode 0600), including username, password, and expires_at. The tool result does not include the JWT.
signup calls POST /auth/signup with no bearer token. The account role is user. It does not replace the stored JWT.
create_user calls POST /auth/users only when the stored token's role is admin.
Before a global stamp or verify, a stored username and password are used to log in again when expires_at is missing or within 5 minutes.
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>.

2.9 KiB Raw Blame History