George Lambert
1ca834900e
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.
60 lines
2.9 KiB
Markdown
60 lines
2.9 KiB
Markdown
# 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>`.
|