verae-mcp-timestamping-server/docs/html/standards.html

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="pandoc" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
  <title>standards</title>
  <style>
    /* Default styles provided by pandoc.
    ** See https://pandoc.org/MANUAL.html#variables-for-html for config info.
    */
    code{white-space: pre-wrap;}
    span.smallcaps{font-variant: small-caps;}
    div.columns{display: flex; gap: min(4vw, 1.5em);}
    div.column{flex: auto; overflow-x: auto;}
    div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
    /* The extra [class] is a hack that increases specificity enough to
       override a similar rule in reveal.js */
    ul.task-list[class]{list-style: none;}
    ul.task-list li input[type="checkbox"] {
      font-size: inherit;
      width: 0.8em;
      margin: 0 0.8em 0.2em -1.6em;
      vertical-align: middle;
    }
    .display.math{display: block; text-align: center; margin: 0.5rem auto;}
  </style>
  <link rel="stylesheet" href="style.css" />
</head>
<body>
<header id="title-block-header">
<h1 class="title">standards</h1>
</header>
<h1 id="standards">Standards</h1>
<p>Rules for the Verae MCP timestamping server.</p>
<h2 id="protocol">Protocol</h2>
<p>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.</p>
<h2 id="hash-only">Hash only</h2>
<ul>
<li>Callers send a SHA-256 digest: 64 lowercase hex characters. A
<code>sha256:</code> prefix is stripped.</li>
<li>The server does not read files, does not accept document bytes, and
does not hash content.</li>
<li>Empty input has the well-known digest
<code>e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855</code>.
Callers may stamp that digest. The server does not invent it from a
missing file.</li>
</ul>
<h2 id="scopes">Scopes</h2>
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<thead>
<tr>
<th>Scope</th>
<th>Where the receipt lives</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>local</code></td>
<td>JSON file, default
<code>~/.verae/mcp-timestamp-local.json</code></td>
</tr>
<tr>
<td><code>shared</code></td>
<td>Same file. There is no separate shared store in this process</td>
</tr>
<tr>
<td><code>global</code></td>
<td><code>POST https://api.veraetime.net/api/timestamp</code> with
<code>wait=true</code></td>
</tr>
</tbody>
</table>
<p><code>want_scope=global</code> on <code>verify</code> asks VeraeTime.
A local receipt cannot satisfy <code>global</code>.</p>
<h2 id="global-history">Global history</h2>
<p><code>hash_report</code> 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 <code>hash_report</code>. An empty list
means “not in the local file,” not “VeraeTime has no record.”</p>
<h2 id="credentials">Credentials</h2>
<ul>
<li>Token: <code>VERAE_GLOBAL_TOKEN</code>, else
<code>access_token</code> / <code>id_token</code> /
<code>auth_token</code> in <code>~/.verae/auth.properties</code>
(<code>VERAE_AUTH_PROPERTIES</code> overrides the path).</li>
<li><code>login</code> writes that file (mode <code>0600</code>),
including <code>username</code>, <code>password</code>, and
<code>expires_at</code>. The tool result does not include the JWT.</li>
<li><code>signup</code> calls <code>POST /auth/signup</code> with no
bearer token. The account role is <code>user</code>. It does not replace
the stored JWT.</li>
<li><code>create_user</code> calls <code>POST /auth/users</code> only
when the stored token’s role is <code>admin</code>.</li>
<li>Before a global stamp or verify, a stored username and password are
used to log in again when <code>expires_at</code> is missing or within 5
minutes.</li>
<li>Do not commit tokens. <code>.env</code> is gitignored.</li>
<li>The local receipt file is mode <code>0600</code> after each
save.</li>
</ul>
<h2 id="nats">NATS</h2>
<p><code>NatsLedger</code> is optional and is not the default. It uses
core NATS request/reply:</p>
<ul>
<li><code>verae.ts.request</code></li>
<li><code>verae.ts.verify</code></li>
<li><code>verae.hash.report</code></li>
</ul>
<p>Job-complete and receipt notifications stay ephemeral core NATS
(<code>verae.ts.completed</code>, <code>verae.ts.receipt</code>). This
server does not put those events on JetStream.</p>
<h2 id="transports">Transports</h2>
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<thead>
<tr>
<th><code>VERAE_MCP_TRANSPORT</code></th>
<th>Bind</th>
</tr>
</thead>
<tbody>
<tr>
<td>unset or <code>stdio</code></td>
<td>Parent process stdin/stdout</td>
</tr>
<tr>
<td><code>streamable-http</code></td>
<td><code>VERAE_MCP_HOST</code> (default <code>127.0.0.1</code>) and
<code>VERAE_MCP_PORT</code> (default <code>8000</code>), path
<code>/mcp</code></td>
</tr>
</tbody>
</table>
<p>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.</p>
<h2 id="errors">Errors</h2>
<p>Invalid digests and unknown scopes raise <code>ToolError</code> with
the <code>ValueError</code> text. HTTP failures from VeraeTime surface
as <code>global timestamp HTTP &lt;status&gt;</code>.</p>
</body>
</html>