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.

github.com/Ente/protoml-parser

Ente/protoml-parser

248 lines (236 loc) • 14.2 kB

HTML

<!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <title>Macro Registry - ProtoML 1.4.2+build67</title> <link rel="stylesheet" href="help.css"> </head> <body> <nav class="topnav"> <a href="../toc.html">Contents</a> ProtoML 1.4.2+build67 </nav> <main class="page"> <h1>Macro Registry</h1> <div class="topic-meta">Topic: <code>macro_registry</code></div> <h2>Explanation</h2> An external ProtoML macro registry can be hosted as a simple static JSON file. This kind of registry is a package index for external macros and pack metadata. It is not the same thing as <code>protoparser register "<dir>" ...</code>, which reports on document collections. A registry may be used in three ways: <ul> <li>as a macro package catalog with <code>packages</code></li> <li>as an author trust directory with <code>authors</code></li> <li>as a mixed registry that provides both</li> </ul> This makes decentralized registries possible: <ul> <li>a public GitHub Pages site</li> <li>an internal company web server</li> <li>a local file share</li> <li>a mounted network path such as an NFS or SMB share</li> <li>any static host that can publish JSON and package files</li> </ul> Recommended minimal registry structure: <pre><code class="language-json">{ "version": 1, "authors": [ { "name": "Alice", "trust": "trusted", "keys": [ { "id": "alice-main", "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----" } ] } ], "packages": [ { "name": "legal-pack", "version": "1.2.0", "description": "Contract and signature macros", "author": "Alice", "trust": "trusted", "manifest": "packs/legal-pack/protoml-pack.json", "source": "packs/legal-pack" } ] }</code></pre> Recommended macro pack structure: <pre><code class="language-text">legal-pack/ manifest.json macros/ clause_box.pml signature_panel.pml themes/ legal.css README.md</code></pre> Recommended pack manifest: <pre><code class="language-json">{ "name": "legal-pack", "version": "1.2.0", "author": "Example Org", "trust": "unknown", "description": "Contract and signature helpers", "macros": [ "macros/clause_box.pml", "macros/signature_panel.pml" ], "themes": [ "themes/legal.css" ], "keywords": ["legal", "contracts", "signatures"], "protoml": ">=1.3.0" }</code></pre> Recommended project definition file: <pre><code class="language-json">{ "version": 1, "registries": [ "https://example.org/protoml/registry.json" ], "packages": [ { "name": "legal-pack", "version": "1.2.0" } ] }</code></pre> Recommended local install target: <code>.protoml/macro-packs/</code> That keeps the repository clean while still making the project reproducible through a single definition file. Macro pack dependencies can be declared in <code>protoml-pack.json</code>. During <code>protoparser macro_install sync</code>, dependencies are resolved automatically. If a dependency entry omits a registry, the current registry is assumed. Trust guidance: <ul> <li>the registry <code>authors</code> list is the preferred place for author trust classification</li> <li>package-level <code>trust</code> is descriptive metadata for discovery and review workflows</li> <li>cryptographic signatures are stored as detached <code>*.sig.json</code> files next to macros or documents</li> <li><code>protoparser trust</code> and <code>protoparser verify</code> can use the same registry for author trust lookup</li> <li>the nearest project <code>protoml.macros.json</code> can wire listed registries into <code>trust</code>, <code>verify</code>, and <code>validate</code> automatically</li> <li><code>-trustRegistry=...</code> is the flag that adds extra registry sources on top of that behavior; it is not a separate command</li> <li>the flag accepts a registry directory, a direct registry JSON path, or an HTTP/HTTPS registry URL</li> <li>the flag is repeatable, so multiple registries can be combined in one command</li> <li>bundled built-in macros can also resolve to <code>trusted</code> without detached signatures when they match the shipped built-in hash manifest and do not trigger hard risk flags</li> <li>if built-in macros should be treated as <code>trusted</code> by the exact same author-signature workflow as external macros, they still need detached signatures and a matching trusted author entry in a documented trust registry</li> <li>package-level <code>trust</code> does not by itself decide runtime trust classification for a macro; author trust, signature status, hard risk flags, and built-in origin checks do</li> <li>a registry with only <code>authors</code> is valid for trust lookup even when it publishes no packages</li> <li>a registry with only <code>packages</code> is valid for install/search workflows even when it publishes no authors</li> <li>commands that resolve author trust simply ignore registries that do not provide matching <code>authors</code> entries</li> </ul> Remote registry workflow: Admin side: <ul> <li>host <code>protoml.registry.json</code> on a stable HTTP or HTTPS URL</li> <li>publish pack files on reachable URLs and keep <code>manifest</code> and <code>source</code> paths valid</li> <li>optionally publish an <code>authors</code> list with trust levels and public keys</li> <li>document whether the registry is reviewed, internal, public, or experimental</li> <li>a simple static web server is enough; no dedicated registry backend is required</li> <li>common company setups are an internal Apache/Nginx site, an intranet static host, or an artifact/file server that exposes plain files</li> </ul> User side: <ul> <li>add the registry with <code>protoparser macro_install add_registry "https://example.org/protoml.registry.json"</code> when it should be part of the project</li> <li>or search it ad hoc with <code>protoparser macro_install search "legal" "https://example.org/protoml.registry.json"</code></li> <li>add the registry to the nearest project <code>protoml.macros.json</code> when <code>trust</code>, <code>verify</code>, or <code>validate</code> should pick it up automatically for files in that project</li> <li>use <code>-trustRegistry=...</code> with <code>trust</code>, <code>verify</code>, or <code>validate -trust=...</code> if the remote registry should also act as an extra author trust source outside the stored project config</li> <li>review the registry owner before treating the registry as trusted</li> <li>prefer <code>trust</code> or <code>verify</code> when you need remote URL registries to be actively fetched</li> <li>if authors and packages are split across different registries, pass each source separately or store both in the project registry list</li> </ul> Local company registry workflow: Admin side: <ul> <li>keep the registry in a shared directory such as <code>Z:\protoml-registry\</code> on Windows or <code>/mnt/protoml-registry/</code> on Linux</li> <li>store <code>protoml.registry.json</code> at the registry root</li> <li>keep pack folders and manifests under that root</li> <li>publish updates through the normal internal review or file-share process used by the team</li> </ul> User side: <ul> <li>add the registry directly with <code>protoparser macro_install add_registry "Z:\\protoml-registry"</code> or <code>protoparser macro_install add_registry "/mnt/protoml-registry"</code></li> <li>add the same path to the nearest project <code>protoml.macros.json</code> when the shared directory should be auto-discovered as an author trust source</li> <li>use <code>-trustRegistry=...</code> when you want to add that source ad hoc without changing project config</li> <li>this is often the simplest option for internal-only teams that do not need HTTP hosting</li> </ul> Current local workflow: <ul> <li>create a registry with <code>protoparser macro_install init_registry</code></li> <li>create packs with <code>protoparser macro_install init_pack</code></li> <li>add or update registry entries with <code>protoparser macro_install registry_add</code></li> <li>add the registry to a project with <code>protoparser macro_install add_registry</code></li> <li>install declared packs with <code>protoparser macro_install sync</code></li> </ul> Recommended trust-aware workflow: 1. Use bundled <code>{{macro_dir}}</code> macros first when the shipped set already covers the need. 2. Create a custom pack only when you need behavior or presentation that is not already covered. 3. Sign the custom macro files in the pack before treating them as production-ready. 4. Publish the signing authors in the registry <code>authors</code> list. 5. Install the pack in the project and verify it with <code>trust</code>, <code>verify</code>, or <code>validate -trust=...</code>. 6. Treat JavaScript and external URLs as explicit review points, even for registry-delivered macros. Split-registry workflow: 1. keep package delivery in one registry if that fits your release process 2. keep trusted authors in a separate reviewed registry if that fits your security process 3. add both registries where needed 4. keep every relevant registry in the nearest project <code>protoml.macros.json</code>, or repeat <code>-trustRegistry=...</code> for ad hoc trust-oriented commands 5. expect install/search to care about <code>packages</code>, and trust/verify/validate to care about <code>authors</code> How to choose between built-ins and registries: <ul> <li>use <code>{{macro_dir}}</code> for shipped built-in macros with the simplest trust story</li> <li>use a registry when you need your own reusable pack catalog across projects or teams</li> <li>use detached signatures plus a registry when your custom macros should resolve to <code>trusted</code></li> <li>use unsigned local macros only for ad hoc or experimental work where <code>unknown</code> is acceptable</li> </ul> Complete signed registry flow: 1. create the registry and the pack 2. create or edit the macro file inside the pack 3. sign the macro file with <code>protoparser sign macro ...</code> 4. add the signing author's public key to the registry <code>authors</code> list 5. add the pack to the registry index 6. consume the registry from a project 7. verify the macro or the full document through project auto-discovery or with explicit <code>-trustRegistry=...</code> Detached sidecar workflow outside a registry: Author side: <ul> <li>sign the macro file with <code>protoparser sign macro ...</code></li> <li>keep the generated <code>*.sig.json</code> file next to the macro</li> <li>distribute the macro, the sidecar, and the public key together</li> </ul> User side: <ul> <li>keep the macro and <code>*.sig.json</code> file together</li> <li>run <code>protoparser verify macro ...</code></li> <li>if there is no registry author entry, treat the macro as cryptographically verified but not registry-trusted</li> </ul> <h2>Examples</h2> <pre><code>End-to-end signed macro registry example: protoparser macro_install init_registry "./my-registry" protoparser macro_install init_pack "legal-pack" "./my-registry" Edit: "./my-registry/packs/legal-pack/macros/legal_pack_sample.pml" Sign the macro: protoparser sign macro "./my-registry/packs/legal-pack/macros/legal_pack_sample.pml" "./keys/alice-private.pem" "Alice" alice-main Add author key to `./my-registry/protoml.registry.json`: { "version": 1, "name": "my-registry", "authors": [ { "name": "Alice", "trust": "trusted", "keys": [ { "id": "alice-main", "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----" } ] } ], "packages": [] } protoparser macro_install registry_add "./my-registry" "./my-registry/packs/legal-pack" protoparser macro_install add_registry "./my-registry" protoparser macro_install add_package "legal-pack" 1.0.0 protoparser macro_install sync Use in a meeting: @macros_import ".protoml/macro-packs/macros.index.pml" @meeting "Minutes" @@macro=legal_pack_sample:title=Hello;text=Signed macro Verify against the registry: protoparser trust "./project/Meeting.pml" protoparser trust "Meeting.pml" -trustRegistry="./my-registry" protoparser verify macro "./my-registry/packs/legal-pack/macros/legal_pack_sample.pml" -trustRegistry="./my-registry" Split registry example: protoparser verify pml "./meetings/board.pml" -trustRegistry="./authors-registry" -trustRegistry="./macro-registry" Company registry examples: protoparser macro_install add_registry "https://intra.example.local/protoml/protoml.registry.json" protoparser macro_install add_registry "Z:\\protoml-registry" protoparser validate "./governance/release-checklist.pml" -trust=strict -trustRegistry="https://intra.example.local/protoml/protoml.registry.json" protoparser validate "./governance/release-checklist.pml" -trust=strict -trustRegistry="Z:\\protoml-registry"</code></pre> </main> </body> </html>