protoml-parser
Version:
ProtoML is a lightweight, declarative markup language designed for writing and structuring meeting protocols, notes and task lists in a human-readable and machine-parseable format.
57 lines (56 loc) • 3.75 kB
HTML
<html>
<head>
<meta charset="UTF-8">
<title>Verify - ProtoML 1.4.2+build67</title>
<link rel="stylesheet" href="help.css">
</head>
<body>
<nav class="topnav">
<a href="../toc.html">Contents</a>
<span class="version">ProtoML 1.4.2+build67</span>
</nav>
<main class="page">
<h1>Verify</h1>
<div class="topic-meta">Topic: <code>verify</code></div>
<h2>Explanation</h2>
<p><code>protoparser verify <macro|pml> <file></code> verifies the detached signature for a macro or a ProtoML document.</p>
<p>Verification happens in two layers:</p>
<ul>
<li>cryptographic verification of the sidecar signature</li>
<li>optional author trust lookup against one or more trust registries</li>
</ul>
<p>Without a registry source, ProtoML can still verify whether the file matches its signature. With <code>-trustRegistry=...</code>, it can also classify the author as <code>trusted</code>, <code>untrusted</code>, or <code>unknown</code>. <code>-trustRegistry=...</code> is a lookup flag, not a separate subcommand. You can point it at a registry directory, a registry JSON file, or an HTTP/HTTPS registry URL. The flag is repeatable, so you can provide more than one registry source. If the target file sits inside a project with <code>protoml.macros.json</code>, ProtoML also auto-discovers the nearest configured project registries and uses them even without the flag.</p>
<p>For bundled built-in macros, trust can also come from the built-in hash manifest even when no detached signature exists. <code>verify</code> still reports detached-signature state explicitly, so a built-in macro may be trusted by origin while still showing a missing signature sidecar.</p>
<p>How to read verification results precisely:</p>
<ul>
<li>signature validity and author trust are related but separate</li>
<li>a valid signature with no matching registry author usually stays <code>unknown</code></li>
<li>a valid signature plus an author marked <code>trusted</code> can elevate external content to <code>trusted</code></li>
<li>an author marked <code>untrusted</code> downgrades the result to <code>untrusted</code></li>
<li>hard risk flags are still authoritative in the full trust workflow, so verification alone is not the whole policy story for macros</li>
<li>package-only registries are harmless during verification because author trust lookup only consumes the registry <code>authors</code> list</li>
<li>author-only registries are also valid trust sources even when they do not publish any macro packages</li>
</ul>
<p>Detached sidecar workflow outside a registry:</p>
<p>Author side:</p>
<ul>
<li>sign the macro or document and distribute the <code>*.sig.json</code> file together with the original file</li>
<li>give users the public key through a separate documented channel</li>
</ul>
<p>User side:</p>
<ul>
<li>verify the file with <code>protoparser verify ...</code></li>
<li>use the result as cryptographic integrity/authorship evidence</li>
<li>if there is no trust registry, the result proves the file matches the signature, but it does not elevate the author to <code>trusted</code></li>
</ul>
<h2>Examples</h2>
<pre><code>protoparser verify macro "./macros/warn_box.pml"
protoparser verify pml "./governance/board.pml"
protoparser verify macro "./macros/warn_box.pml" -trustRegistry="./my-registry"
protoparser verify macro "./macros/warn_box.pml" -trustRegistry="./authors-registry" -trustRegistry="./package-registry"
protoparser verify pml "./meetings/board.pml" -trustRegistry="https://example.org/protoml.registry.json"
protoparser verify macro "./shared/warn_box.pml"</code></pre>
</main>
</body>
</html>