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
6 changed files with 989 additions and 0 deletions

258
docs/html/api.html Normal file
View file

@ -0,0 +1,258 @@
<!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>api</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;}
/* CSS for syntax highlighting */
html { -webkit-text-size-adjust: 100%; }
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code span.at { color: #7d9029; } /* Attribute */
code span.bn { color: #40a070; } /* BaseN */
code span.bu { color: #008000; } /* BuiltIn */
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code span.ch { color: #4070a0; } /* Char */
code span.cn { color: #880000; } /* Constant */
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
code span.dt { color: #902000; } /* DataType */
code span.dv { color: #40a070; } /* DecVal */
code span.er { color: #ff0000; font-weight: bold; } /* Error */
code span.ex { } /* Extension */
code span.fl { color: #40a070; } /* Float */
code span.fu { color: #06287e; } /* Function */
code span.im { color: #008000; font-weight: bold; } /* Import */
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
code span.op { color: #666666; } /* Operator */
code span.ot { color: #007020; } /* Other */
code span.pp { color: #bc7a00; } /* Preprocessor */
code span.sc { color: #4070a0; } /* SpecialChar */
code span.ss { color: #bb6688; } /* SpecialString */
code span.st { color: #4070a0; } /* String */
code span.va { color: #19177c; } /* Variable */
code span.vs { color: #4070a0; } /* VerbatimString */
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
</style>
<link rel="stylesheet" href="style.css" />
</head>
<body>
<header id="title-block-header">
<h1 class="title">api</h1>
</header>
<h1 id="tool-api">Tool API</h1>
<p>Server name: <code>verae-timestamping</code>.</p>
<h2 id="stamp">stamp</h2>
<table>
<colgroup>
<col style="width: 33%" />
<col style="width: 33%" />
<col style="width: 33%" />
</colgroup>
<thead>
<tr>
<th>Argument</th>
<th>Default</th>
<th>Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>sha256</code></td>
<td>required</td>
<td>64 hex characters</td>
</tr>
<tr>
<td><code>scope</code></td>
<td><code>local</code></td>
<td><code>local</code>, <code>shared</code>, or <code>global</code></td>
</tr>
<tr>
<td><code>cube_id</code></td>
<td>empty</td>
<td>Stored on the local receipt. Sent only as a local field on the
global receipt object; the VeraeTime POST body is the digest</td>
</tr>
<tr>
<td><code>org_id</code></td>
<td>empty</td>
<td>Local idempotency key. Ignored by the global client</td>
</tr>
</tbody>
</table>
<p>Returns <code>{ "receipts": [ Receipt ] }</code>.</p>
<p>Receipt fields: <code>receipt_id</code>, <code>hash</code>,
<code>scope</code>, <code>cube_id</code>, <code>org_id</code>,
<code>created_at</code>, <code>merkle</code>,
<code>restamp_of</code>.</p>
<h2 id="verify">verify</h2>
<table>
<colgroup>
<col style="width: 33%" />
<col style="width: 33%" />
<col style="width: 33%" />
</colgroup>
<thead>
<tr>
<th>Argument</th>
<th>Default</th>
<th>Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>receipt_id</code></td>
<td>required</td>
<td>Local id or VeraeTime certificate / job id</td>
</tr>
<tr>
<td><code>want_scope</code></td>
<td>empty</td>
<td><code>global</code> forces VeraeTime. A weaker scope fails closed
when the stored scope ranks lower</td>
</tr>
</tbody>
</table>
<p>Returns
<code>{ "valid": bool, "error": string or null, "receipt": Receipt or null }</code>.</p>
<p>Scope rank: local &lt; shared &lt; global.</p>
<h2 id="hash_report">hash_report</h2>
<table>
<thead>
<tr>
<th>Argument</th>
<th>Default</th>
<th>Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>sha256</code></td>
<td>required</td>
<td>Digest to list</td>
</tr>
<tr>
<td><code>org_id</code></td>
<td>empty</td>
<td>Filter when set</td>
</tr>
<tr>
<td><code>want_scope</code></td>
<td>empty</td>
<td>Drop receipts below this rank</td>
</tr>
</tbody>
</table>
<p>Returns <code>{ "receipts": [ ... ] }</code> from the local file.
Global-only certificates are not listed.</p>
<h2 id="environment">Environment</h2>
<table>
<thead>
<tr>
<th>Name</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>VERAE_GLOBAL_URL</code></td>
<td><code>https://api.veraetime.net</code></td>
</tr>
<tr>
<td><code>VERAE_GLOBAL_TOKEN</code></td>
<td>empty (then auth.properties)</td>
</tr>
<tr>
<td><code>VERAE_AUTH_PROPERTIES</code></td>
<td><code>~/.verae/auth.properties</code></td>
</tr>
<tr>
<td><code>VERAE_LEDGER_PATH</code></td>
<td><code>~/.verae/mcp-timestamp-local.json</code></td>
</tr>
<tr>
<td><code>VERAE_MCP_TRANSPORT</code></td>
<td><code>stdio</code></td>
</tr>
<tr>
<td><code>VERAE_MCP_HOST</code></td>
<td><code>127.0.0.1</code></td>
</tr>
<tr>
<td><code>VERAE_MCP_PORT</code></td>
<td><code>8000</code></td>
</tr>
<tr>
<td><code>VERAE_MCP_CORS</code></td>
<td>unset. <code>1</code> adds CORS for the sample page</td>
</tr>
</tbody>
</table>
<h2 id="client-config-stdio">Client config (stdio)</h2>
<div class="sourceCode" id="cb1"><pre
class="sourceCode json"><code class="sourceCode json"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;mcpServers&quot;</span><span class="fu">:</span> <span class="fu">{</span></span>
<span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;verae-timestamping&quot;</span><span class="fu">:</span> <span class="fu">{</span></span>
<span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;command&quot;</span><span class="fu">:</span> <span class="st">&quot;uv&quot;</span><span class="fu">,</span></span>
<span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">&quot;args&quot;</span><span class="fu">:</span> <span class="ot">[</span><span class="st">&quot;run&quot;</span><span class="ot">,</span> <span class="st">&quot;--directory&quot;</span><span class="ot">,</span> <span class="st">&quot;/Users/marchon/research/modelcontextprotocol/verae-mcp-timestamping-server&quot;</span><span class="ot">,</span> <span class="st">&quot;verae-mcp-timestamping-server&quot;</span><span class="ot">]</span></span>
<span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
<span id="cb1-7"><a href="#cb1-7" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
<span id="cb1-8"><a href="#cb1-8" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</body>
</html>

View file

@ -0,0 +1,95 @@
<!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>architecture</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">architecture</h1>
</header>
<h1 id="architecture">Architecture</h1>
<h2 id="flow">Flow</h2>
<ol type="1">
<li>An MCP client calls <code>stamp</code>, <code>verify</code>, or
<code>hash_report</code>.</li>
<li><code>RoutingLedger</code> sends <code>scope=global</code> to
<code>GlobalLedger</code> and every other scope to
<code>FileLedger</code>.</li>
<li><code>FileLedger</code> keeps an idempotent JSON list. The same
digest, org, and scope returns the existing receipt.</li>
<li><code>GlobalClient</code> posts the digest to VeraeTime and, when
the body has no certificate yet, polls
<code>/api/status/{jobId}</code>.</li>
<li><code>verify</code> with <code>want_scope=global</code> posts
<code>{ "certificate": "&lt;id&gt;" }</code> to
<code>/api/verify</code>. Otherwise it checks the local file first, then
VeraeTime.</li>
</ol>
<h2 id="modules">Modules</h2>
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<thead>
<tr>
<th>Module</th>
<th>Role</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>server.py</code></td>
<td>MCP tools and process entry</td>
</tr>
<tr>
<td><code>ledger.py</code></td>
<td>Receipt model, memory ledger, file ledger, router</td>
</tr>
<tr>
<td><code>global_client.py</code></td>
<td>VeraeTime HTTPS client; blocking I/O runs in a worker thread</td>
</tr>
<tr>
<td><code>nats_ledger.py</code></td>
<td>Optional leaf <code>locald</code> client</td>
</tr>
</tbody>
</table>
<h2 id="idempotency">Idempotency</h2>
<p>Local stamps are idempotent per digest + org + scope. Global stamps
send <code>restamp: false</code> and <code>wait: true</code>. VeraeTime
may return the same certificate for the same digest. This server does
not cache global receipts in the local file.</p>
<h2 id="what-this-process-is-not">What this process is not</h2>
<p>It does not replace <code>verae-timestamp</code> /
<code>locald</code>. It does not write JetStream. It does not store
document bytes. Memory ledger exists for tests and for
<code>mcp dev</code> when a caller injects it. <code>main()</code>
always builds <code>RoutingLedger</code>.</p>
</body>
</html>

19
docs/html/index.html Normal file
View file

@ -0,0 +1,19 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Verae MCP timestamping server</title>
<link rel="stylesheet" href="style.css">
</head>
<body>
<h1>Verae MCP timestamping server</h1>
<p>Hash-only stamps for assistants that speak the Model Context Protocol.</p>
<ul>
<li><a href="operator-guide.html">Operator guide</a> (<a href="../pdf/operator-guide.pdf">PDF</a>)</li>
<li><a href="architecture.html">Architecture</a> (<a href="../pdf/architecture.pdf">PDF</a>)</li>
<li><a href="api.html">Tool API</a> (<a href="../pdf/api.pdf">PDF</a>)</li>
<li><a href="standards.html">Standards</a> (<a href="../pdf/standards.pdf">PDF</a>)</li>
<li><a href="../../site/index.html">Sample page</a></li>
</ul>
</body>
</html>

View file

@ -0,0 +1,128 @@
<!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>operator-guide</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;}
/* CSS for syntax highlighting */
html { -webkit-text-size-adjust: 100%; }
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code span.at { color: #7d9029; } /* Attribute */
code span.bn { color: #40a070; } /* BaseN */
code span.bu { color: #008000; } /* BuiltIn */
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code span.ch { color: #4070a0; } /* Char */
code span.cn { color: #880000; } /* Constant */
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
code span.dt { color: #902000; } /* DataType */
code span.dv { color: #40a070; } /* DecVal */
code span.er { color: #ff0000; font-weight: bold; } /* Error */
code span.ex { } /* Extension */
code span.fl { color: #40a070; } /* Float */
code span.fu { color: #06287e; } /* Function */
code span.im { color: #008000; font-weight: bold; } /* Import */
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
code span.op { color: #666666; } /* Operator */
code span.ot { color: #007020; } /* Other */
code span.pp { color: #bc7a00; } /* Preprocessor */
code span.sc { color: #4070a0; } /* SpecialChar */
code span.ss { color: #bb6688; } /* SpecialString */
code span.st { color: #4070a0; } /* String */
code span.va { color: #19177c; } /* Variable */
code span.vs { color: #4070a0; } /* VerbatimString */
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
</style>
<link rel="stylesheet" href="style.css" />
</head>
<body>
<header id="title-block-header">
<h1 class="title">operator-guide</h1>
</header>
<h1 id="operator-guide">Operator guide</h1>
<h2 id="install">Install</h2>
<div class="sourceCode" id="cb1"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="bu">cd</span> /Users/marchon/research/modelcontextprotocol/verae-mcp-timestamping-server</span>
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="ex">uv</span> sync <span class="at">--group</span> dev</span></code></pre></div>
<h2 id="run-stdio">Run stdio</h2>
<div class="sourceCode" id="cb2"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="ex">uv</span> run verae-mcp-timestamping-server</span></code></pre></div>
<h2 id="run-streamable-http">Run Streamable HTTP</h2>
<div class="sourceCode" id="cb3"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="va">VERAE_MCP_TRANSPORT</span><span class="op">=</span>streamable-http <span class="ex">uv</span> run verae-mcp-timestamping-server</span></code></pre></div>
<p>The listener is <code>http://127.0.0.1:8000/mcp</code>.</p>
<p>For the sample page on another origin:</p>
<div class="sourceCode" id="cb4"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="va">VERAE_MCP_CORS</span><span class="op">=</span>1 <span class="va">VERAE_MCP_TRANSPORT</span><span class="op">=</span>streamable-http <span class="ex">uv</span> run verae-mcp-timestamping-server</span></code></pre></div>
<p>A page served from the public internet still cannot call
<code>127.0.0.1</code> from current browsers. Open
<code>site/index.html</code> on the same machine, or put TLS and an
access control in front of a non-loopback bind you choose yourself.</p>
<h2 id="global-token">Global token</h2>
<div class="sourceCode" id="cb5"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="co"># POST https://api.veraetime.net/auth/login and store access_token=</span></span>
<span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="co"># in ~/.verae/auth.properties (mode 600), or:</span></span>
<span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a><span class="bu">export</span> <span class="va">VERAE_GLOBAL_TOKEN</span><span class="op">=</span>...</span></code></pre></div>
<h2 id="tests">Tests</h2>
<div class="sourceCode" id="cb6"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="ex">uv</span> run pytest</span></code></pre></div>
<p>Stamp traces (live VeraeTime) are a separate script. They write
<code>debug-trace/&lt;YYYY-MM-DDTHHMMSSZ&gt;-&lt;slug&gt;/</code>:</p>
<div class="sourceCode" id="cb7"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="ex">uv</span> run python scripts/transaction_log_test.py</span></code></pre></div>
<h2 id="build-these-documents">Build these documents</h2>
<div class="sourceCode" id="cb8"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="fu">bash</span> scripts/build-docs.sh</span></code></pre></div>
<p>HTML lands in <code>docs/html/</code>. PDF lands in
<code>docs/pdf/</code>.</p>
</body>
</html>

141
docs/html/standards.html Normal file
View file

@ -0,0 +1,141 @@
<!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>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>

1
docs/html/style.css Normal file
View file

@ -0,0 +1 @@
body{font-family:Georgia,serif;max-width:42rem;margin:2rem auto;padding:0 1rem;line-height:1.45}code,pre{font-family:ui-monospace,monospace}table{border-collapse:collapse}td,th{border:1px solid #ccc;padding:0.3rem 0.5rem}