docs: HTML and PDF set plus optional CORS

WhatToChange: recommended-changes/2026-09-21-docs-and-cors/
  What-to-Change.md
  What-to-Change-To.md
  How-to-implement-the-changes.md

What was actually done:
- Markdown, HTML, and PDF for standards, architecture, API, and the operator guide.
- README points at scripts/build-docs.sh.
- VERAE_MCP_CORS=1 enables CORS and JSON responses on the Streamable HTTP app.

What was not done:
- (none)
This commit is contained in:
George Lambert 2026-09-21 14:13:07 -04:00
commit 840755c84a

63
docs/api.md Normal file
View file

@ -0,0 +1,63 @@
# Tool API
Server name: `verae-timestamping`.
## stamp
| Argument | Default | Meaning |
| --- | --- | --- |
| `sha256` | required | 64 hex characters |
| `scope` | `local` | `local`, `shared`, or `global` |
| `cube_id` | empty | Stored on the local receipt. Sent only as a local field on the global receipt object; the VeraeTime POST body is the digest |
| `org_id` | empty | Local idempotency key. Ignored by the global client |
Returns `{ "receipts": [ Receipt ] }`.
Receipt fields: `receipt_id`, `hash`, `scope`, `cube_id`, `org_id`, `created_at`, `merkle`, `restamp_of`.
## verify
| Argument | Default | Meaning |
| --- | --- | --- |
| `receipt_id` | required | Local id or VeraeTime certificate / job id |
| `want_scope` | empty | `global` forces VeraeTime. A weaker scope fails closed when the stored scope ranks lower |
Returns `{ "valid": bool, "error": string or null, "receipt": Receipt or null }`.
Scope rank: local < shared < global.
## hash_report
| Argument | Default | Meaning |
| --- | --- | --- |
| `sha256` | required | Digest to list |
| `org_id` | empty | Filter when set |
| `want_scope` | empty | Drop receipts below this rank |
Returns `{ "receipts": [ ... ] }` from the local file. Global-only certificates are not listed.
## Environment
| Name | Default |
| --- | --- |
| `VERAE_GLOBAL_URL` | `https://api.veraetime.net` |
| `VERAE_GLOBAL_TOKEN` | empty (then auth.properties) |
| `VERAE_AUTH_PROPERTIES` | `~/.verae/auth.properties` |
| `VERAE_LEDGER_PATH` | `~/.verae/mcp-timestamp-local.json` |
| `VERAE_MCP_TRANSPORT` | `stdio` |
| `VERAE_MCP_HOST` | `127.0.0.1` |
| `VERAE_MCP_PORT` | `8000` |
| `VERAE_MCP_CORS` | unset. `1` adds CORS for the sample page |
## Client config (stdio)
```json
{
"mcpServers": {
"verae-timestamping": {
"command": "uv",
"args": ["run", "--directory", "/Users/marchon/research/modelcontextprotocol/verae-mcp-timestamping-server", "verae-mcp-timestamping-server"]
}
}
}
```