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.
99 lines
3.5 KiB
Markdown
99 lines
3.5 KiB
Markdown
# 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": [ ... ] }`. `want_scope=global` queries VeraeTime `GET /api/hash/{sha256}` (Carfax). Empty `want_scope` merges the local file ledger with the central history.
|
|
|
|
## login
|
|
|
|
| Argument | Default | Meaning |
|
|
| --- | --- | --- |
|
|
| `username` | required | VeraeTime account |
|
|
| `password` | required | VeraeTime password |
|
|
|
|
`POST /auth/login`. Stores `access_token`, `id_token`, `auth_token`, `expires_at`, `username`, and `password` in the auth properties file (mode `0600`) and replaces the in-memory JWT. Returns `username`, `role`, and `expires_at`. The JWT is not returned.
|
|
|
|
## session
|
|
|
|
No arguments. `GET /auth/validate` with the stored JWT.
|
|
|
|
Returns `valid`, `username`, `role`, and `expires_at`.
|
|
|
|
## signup
|
|
|
|
| Argument | Default | Meaning |
|
|
| --- | --- | --- |
|
|
| `username` | required | New account |
|
|
| `password` | required | New password |
|
|
|
|
`POST /auth/signup` with no bearer token. The timestamping service creates the account with role `user`. Returns `id`, `username`, and `role`. Does not replace the JWT stored for `stamp`. A new account calls `login` to become the stored session. `create_user` remains the admin path and can set `admin`.
|
|
|
|
## create_user
|
|
|
|
| Argument | Default | Meaning |
|
|
| --- | --- | --- |
|
|
| `username` | required | New account |
|
|
| `password` | required | New password |
|
|
| `role` | required | `user` or `admin` |
|
|
|
|
`POST /auth/users` with the stored JWT. Refuses unless `session` reports role `admin`. Returns `id`, `username`, and `role`. Public registration is `signup`. `create_user` is how an admin sets a role.
|
|
|
|
A stored login is refreshed when `stamp` or `verify` runs and `expires_at` is missing or within 5 minutes, if `username` and `password` are in the auth file.
|
|
|
|
## 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"]
|
|
}
|
|
}
|
|
}
|
|
```
|