George Lambert
c3e0cd3abb
setup registers or logs in and writes ~/.verae/auth.properties without printing the JWT. A caller bearer is used for stamp and verify instead of the host login. VERAE_MCP_OAUTH=1 serves the browser account page. site/index.html is the public install guide.
356 lines
12 KiB
HTML
356 lines
12 KiB
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>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 < shared < 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="login">login</h2>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Argument</th>
|
|
<th>Default</th>
|
|
<th>Meaning</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>username</code></td>
|
|
<td>required</td>
|
|
<td>VeraeTime account</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>password</code></td>
|
|
<td>required</td>
|
|
<td>VeraeTime password</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p><code>POST /auth/login</code>. Stores <code>access_token</code>,
|
|
<code>id_token</code>, <code>auth_token</code>, <code>expires_at</code>,
|
|
<code>username</code>, and <code>password</code> in the auth properties
|
|
file (mode <code>0600</code>) and replaces the in-memory JWT. Returns
|
|
<code>username</code>, <code>role</code>, and <code>expires_at</code>.
|
|
The JWT is not returned.</p>
|
|
<h2 id="session">session</h2>
|
|
<p>No arguments. <code>GET /auth/validate</code> with the stored
|
|
JWT.</p>
|
|
<p>Returns <code>valid</code>, <code>username</code>, <code>role</code>,
|
|
and <code>expires_at</code>.</p>
|
|
<h2 id="signup">signup</h2>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Argument</th>
|
|
<th>Default</th>
|
|
<th>Meaning</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>username</code></td>
|
|
<td>required</td>
|
|
<td>New account</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>password</code></td>
|
|
<td>required</td>
|
|
<td>New password</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p><code>POST /auth/signup</code> with no bearer token. The timestamping
|
|
service creates the account with role <code>user</code>. Returns
|
|
<code>id</code>, <code>username</code>, and <code>role</code>. Does not
|
|
replace the JWT stored for <code>stamp</code>. A new account calls
|
|
<code>login</code> to become the stored session.
|
|
<code>create_user</code> remains the admin path and can set
|
|
<code>admin</code>.</p>
|
|
<h2 id="create_user">create_user</h2>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Argument</th>
|
|
<th>Default</th>
|
|
<th>Meaning</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>username</code></td>
|
|
<td>required</td>
|
|
<td>New account</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>password</code></td>
|
|
<td>required</td>
|
|
<td>New password</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>role</code></td>
|
|
<td>required</td>
|
|
<td><code>user</code> or <code>admin</code></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p><code>POST /auth/users</code> with the stored JWT. Refuses unless
|
|
<code>session</code> reports role <code>admin</code>. Returns
|
|
<code>id</code>, <code>username</code>, and <code>role</code>. Public
|
|
registration is <code>signup</code>. <code>create_user</code> is how an
|
|
admin sets a role.</p>
|
|
<p>A stored login is refreshed when <code>stamp</code> or
|
|
<code>verify</code> runs and <code>expires_at</code> is missing or
|
|
within 5 minutes, if <code>username</code> and <code>password</code> are
|
|
in the auth file.</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">"mcpServers"</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">"verae-timestamping"</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">"command"</span><span class="fu">:</span> <span class="st">"uv"</span><span class="fu">,</span></span>
|
|
<span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"args"</span><span class="fu">:</span> <span class="ot">[</span><span class="st">"run"</span><span class="ot">,</span> <span class="st">"--directory"</span><span class="ot">,</span> <span class="st">"/Users/marchon/research/modelcontextprotocol/verae-mcp-timestamping-server"</span><span class="ot">,</span> <span class="st">"verae-mcp-timestamping-server"</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>
|