@ust-protocol/cli 1.0.0-rc.2

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,28 @@
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+# ust — the reference CLI
+
+One entrypoint for [UST 1.0](https://github.com/thelabmd/UST-Protocol). The Go binary reproduces this surface, so `ust` is one static, language-agnostic tool.
+
+```bash
+npm i -g @ust-protocol/cli     # installs the `ust` command
+npx @ust-protocol/cli verify doc.json   # or one-shot, no install
+```
+
+```
+ust verify <file|->          verify a transcript (blob / base64 / json). exit 0 = VALID, 1 = not.
+ust canon  <file|->          print the canonical bytes + hash — diff your other-language impl against this
+ust genesis --domain <d>     run the HIGH genesis ceremony
+```
+
+## `ust genesis`
+```
+ust genesis --domain noosphere.md --profile silver --dns cf-api
+```
+- `--profile bronze|silver|gold` — capacity/rigor ladder (gold forces a passphrase-encrypted backup + warns `ASSURANCE LIMIT: software-generated extractable root` unless `--signer` supplies a hardware root)
+- `--dns manual` prints the `_ust` TXT to paste; `--dns cf-api` upserts it via the Cloudflare API (zone-scoped `CF_TOKEN`, never account-wide) and **confirms it with a DNS-over-HTTPS readback** before proceeding — Vercel-style, idempotent
+- `--max-partitions N` — the signed capacity in the genesis (bounds earned by ceremony)
+- `--witness url,url` — witness endpoints to PREPARE (printed for the operator; this CLI does not run the exchange)
+
+The ceremony: generate the root key → build the self-signed genesis + a key-log adding an operational key → back up the root (split + cold) → publish `.well-known/ust-genesis` (the CLI fetches it, **verifies it, and matches its content_hash** — fail-closed) → then PREPARES the witness + anchor stage (the operator executes those). Outputs: **two verifiable UST** (`ust-genesis`, `ust-keylog-0` — `ust verify` them) + an **encrypted PKCS#8 root-key backup** (`genesis-key.enc.b64` — NOT a UST) for operator-managed split cold storage. The CLI self-verifies its outputs before finishing.
+
+The MCP holds no key; this CLI signs locally with a key that stays on your machine.

package/index.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// `ust` — the reference CLI. One command hides each ceremony: verify, canon (DX diagnostic), genesis (#37).
+// The Go binary (#34) reproduces this surface so `ust` is one static, language-agnostic entrypoint.
+//
+// The ceremony CORE is exported as pure functions (buildCeremony / checkPublished / cfUpsert / stageSummary /
+// encryptKey) so a notary tool is TESTABLE end-to-end without a live network — the 9th-audit regression suite
+// (regression.mjs) drives them directly. cmdGenesis is only the readline/network orchestrator around them.
+import { createInterface } from 'node:readline/promises';
+import { readFileSync, writeFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createCipheriv, scryptSync, randomBytes } from 'node:crypto';
+import * as P from 'ust-protocol';
+import * as W from '@ust-protocol/web-signer';
+
+const arg = (name, def) => { const i = process.argv.indexOf('--' + name); return i > -1 ? (process.argv[i + 1] ?? true) : def; };
+const die = (msg) => { console.error('✗ ' + msg); process.exit(1); };
+const HEADER = 'UST/1.0; ref=pkg:npm/ust-protocol; web=https://thelabmd.github.io/UST-Protocol/; call=verify(doc,{context:"data"}); hash=domain-separated; trust=resolve-by-name; proves=bytes+key+time';
+export const decodeInput = (raw) => {
+  let s = raw.trim(); const m = '———UST(base64)———';
+  if (s.includes(m)) s = s.slice(s.lastIndexOf(m) + m.length).trim();
+  return s.startsWith('{') ? JSON.parse(s) : JSON.parse(Buffer.from(s.replace(/\s+/g, ''), 'base64').toString('utf8'));
+};
+const nowFrame = () => W.nowFrame();
+// The verify context follows the record's own class: a genesis/key-log frame verifies as 'key', everything
+// else as 'data'. This is why `ust verify ust-genesis` just works — no one should need to know the context.
+export const contextFor = (doc) => (doc?.state?.id?.class === 'genesis' || doc?.state?.id?.class === 'key') ? 'key' : 'data';
+
+// ─── ceremony CORE (pure, exported — a notary tool must be verifiable by tests, not just by eye) ─────────
+
+export const encryptKey = (pkcs8, pass) => {
+  const salt = randomBytes(16), iv = randomBytes(12), key = scryptSync(pass, salt, 32);
+  const c = createCipheriv('aes-256-gcm', key, iv);
+  const ct = Buffer.concat([c.update(pkcs8), c.final()]);
+  return Buffer.concat([salt, iv, c.getAuthTag(), ct]).toString('base64');
+};
+
+// Build genesis + key-log[0] (adds an operational key) and SELF-CHECK both (fail-closed, 9th audit #6):
+// a ceremony tool must never emit an output it hasn't verified. Throws before returning if either fails.
+// `warnings` carries the gold ASSURANCE LIMIT so the orchestrator (and the test) can assert it (9th audit #5).
+export async function buildCeremony({ domain, profile = 'silver', maxP, signerRef }) {
+  const warnings = [];
+  if (profile === 'gold' && !signerRef) warnings.push('ASSURANCE LIMIT: software-generated extractable root (not a hardware ceremony). For a true gold root use --signer pkcs11:… / an air-gapped device.');
+  const root = await W.generateSigner({ extractable: true });
+  const pkcs8 = Buffer.from(await crypto.subtle.exportKey('pkcs8', root.privateKey));
+  const { ust_id, time } = nowFrame();
+  const genValue = { pub: root.pub, role: 'name-binding-root', ...(maxP ? { max_partitions: String(maxP) } : {}) };
+  const genesis = await W.seal(P.buildState({ domain_shard: domain, ust_id, key_id: root.key_id, class: 'genesis' }, time, { genesis: { kind: 'captured', value: genValue } }), root);
+  const genHash = P.contentHash(genesis);
+  const op = await W.generateSigner();
+  const keylog0 = await W.seal(P.buildKeyLogEntry({ domain_shard: domain, ust_id, key_id: root.key_id }, time, { op: 'add', pub: op.pub, new_key_id: op.key_id }, genHash), root);
+  if (!P.isValid(P.verify(genesis))) throw new Error('self-check FAILED: genesis does not verify');
+  if (!P.isValid(P.verify(keylog0, { context: 'key' }))) throw new Error('self-check FAILED: key-log[0] does not verify');
+  return { genesis, keylog0, genHash, op, pkcs8, warnings };
+}
+
+// Fail-closed check of the published well-known: it must VERIFY and its content_hash must MATCH the genesis
+// we built (a semantic UST match, not a transport byte-compare — 9th audit #1). Throws on any mismatch.
+export function checkPublished(liveText, genHash) {
+  const liveDoc = decodeInput(liveText);
+  if (!P.isValid(P.verify(liveDoc))) throw new Error('published document does not VERIFY');
+  if (P.contentHash(liveDoc) !== genHash) throw new Error('published document is not this genesis (content_hash differs) — republish exactly the ust-genesis file');
+  return liveDoc;
+}
+
+// Cloudflare one-click: UPSERT the _ust TXT (find → PUT if present, else POST) then CONFIRM it via a
+// DNS-over-HTTPS readback (idempotent + fail-closed, 9th audit #7). fetchImpl/sleep are injected so the
+// regression suite exercises the update-path and the readback-failure-path with no live network.
+export async function cfUpsert({ domain, txt, genHash, token, fetchImpl = fetch, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) }) {
+  if (!token) throw new Error('cf-api needs a ZONE-scoped CF_TOKEN (DNS:edit for this zone — never account-wide)');
+  const cf = (path, init) => fetchImpl('https://api.cloudflare.com/client/v4' + path, { ...init, headers: { Authorization: 'Bearer ' + token, 'content-type': 'application/json', ...(init?.headers) } }).then((r) => r.json());
+  const zone = (await cf(`/zones?name=${domain}`)).result?.[0]; if (!zone) throw new Error('CF zone not found / token cannot see ' + domain);
+  const rec = `_ust.${domain}`;
+  const existing = (await cf(`/zones/${zone.id}/dns_records?type=TXT&name=${rec}`)).result?.[0];   // idempotent
+  const body = JSON.stringify({ type: 'TXT', name: rec, content: txt, ttl: 300 });
+  const w = existing
+    ? await cf(`/zones/${zone.id}/dns_records/${existing.id}`, { method: 'PUT', body })
+    : await cf(`/zones/${zone.id}/dns_records`, { method: 'POST', body });
+  if (!w.success) throw new Error('CF write failed: ' + (w.errors?.[0]?.message || '?'));
+  let seen = false;
+  for (let i = 0; i < 6 && !seen; i++) {
+    const doh = await fetchImpl(`https://cloudflare-dns.com/dns-query?name=${rec}&type=TXT`, { headers: { accept: 'application/dns-json' } }).then((r) => r.json()).catch(() => ({}));
+    seen = (doh.Answer || []).some((a) => (a.data || '').replace(/"/g, '').includes(genHash));
+    if (!seen) await sleep(3000);
+  }
+  if (!seen) throw new Error('CF wrote the record but DoH readback did not confirm it (propagation) — re-run or verify manually');
+  return { action: existing ? 'updated' : 'created' };
+}
+
+// The witness/anchor stage is PREPARED, never executed by this CLI (9th audit #2). Exported so the
+// regression suite asserts the wording can't silently regress to a false "witnesses verified / anchored".
+export function stageSummary({ genHash, witnesses = [], profile }) {
+  return [
+    'witness/anchor STAGE PREPARED (not executed by this CLI):',
+    'witnesses to contact: ' + (witnesses.length ? witnesses.join(', ') : (profile === 'bronze' ? 'self (bronze — no external witness)' : 'none supplied — add --witness url,url for silver/gold')),
+    'anchor: queue ' + genHash + ' into your anchor chain → git + OTS/Bitcoin (operator job)',
+  ];
+}
+
+// ─── ust verify <file|-> ─────────────────────────────────────────────────────────────────────────────
+async function cmdVerify() {
+  const src = process.argv[3];
+  if (!src) die('usage: ust verify <file | - for stdin> [--context data|key]');
+  const raw = src === '-' ? readFileSync(0, 'utf8') : readFileSync(src, 'utf8');
+  let doc; try { doc = decodeInput(raw); } catch (e) { die('not a UST blob/base64/json: ' + e.message); }
+  const r = P.verify(doc, { context: arg('context', null) || contextFor(doc) });
+  console.log(r.result + (r.error ? '  (' + r.error + (r.detail ? ' — ' + r.detail : '') + ')' : ''));
+  if (P.isValid(r)) {
+    console.log('  identity : ' + r.identity.strength + ' (mode ' + r.identity.mode + ')  ' + (r.publisher ? 'publisher ' + r.publisher : 'publisher_claimed ' + r.publisher_claimed));
+    console.log('  time     : ' + r.time.strength + '/' + r.time.status + '   completeness: ' + r.completeness);
+    console.log('  ust_id   : ' + r.ust_id + '   class ' + r.class + '   content_hash ' + r.content_hash);
+  }
+  process.exit(P.isValid(r) ? 0 : 1);
+}
+
+// ─── ust canon <file|-> — the DX diagnostic (#41): print the canonical string + hash so any-language devs diff ─
+async function cmdCanon() {
+  const src = process.argv[3];
+  if (!src) die('usage: ust canon <file | - for stdin>   # prints canonical bytes + hash to diff cross-language');
+  const raw = src === '-' ? readFileSync(0, 'utf8') : readFileSync(src, 'utf8');
+  let v; try { v = JSON.parse(raw); } catch (e) { die('not JSON: ' + e.message); }
+  let canonical; try { canonical = P.canon(v); } catch (e) { die('E-CANON: ' + (e.detail || e.message) + '  (values must be NFC strings; no numbers/bools/nulls — §5)'); }
+  console.log(canonical);
+  console.error('# sha256: ' + P.H('ust:state', canonical).slice(7));
+}
+
+// ─── ust genesis --domain <d> [--profile] [--dns] — the ceremony (#37), orchestrating the core above ──
+async function cmdGenesis() {
+  const domain = arg('domain'); if (!domain || domain === true) die('usage: ust genesis --domain <name> [--profile bronze|silver|gold] [--dns manual|cf-api] [--signer <ref>] [--witness url,url] [--max-partitions N] [--out .]');
+  const profile = arg('profile', 'silver');
+  const dns = arg('dns', 'manual');
+  const outDir = arg('out', '.');
+  const maxP = arg('max-partitions', profile === 'gold' ? 256 : profile === 'silver' ? 64 : null);
+  const signerRef = arg('signer', null);
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => rl.question(q);
+  console.log(`\n  ust genesis — ceremony for ${domain} (profile: ${profile})\n`);
+
+  // 1–2. root key + genesis + key-log[0], all self-checked (fail-closed) inside buildCeremony
+  let built; try { built = await buildCeremony({ domain, profile, maxP, signerRef }); }
+  catch (e) { rl.close(); die(e.message); }
+  const { genesis, keylog0, genHash, op, pkcs8, warnings } = built;
+  for (const w of warnings) console.log('  ⚠  ' + w);
+  console.log('  1/5  ROOT key generated');
+  console.log('  2/5  genesis built (self-signed) + key-log[0] adds an operational key');
+  console.log('       genesis content_hash: ' + genHash);
+
+  // backup the root key (gold forces a passphrase → AES-256-GCM; the file is an encrypted blob, NOT a UST)
+  let pass = '';
+  if (profile === 'gold') { while (pass.length < 8) pass = await ask('       set a passphrase for the root-key backup (≥8 chars, split & cold-store): '); }
+  const backup = pass ? encryptKey(pkcs8, pass) : pkcs8.toString('base64');
+  writeFileSync(`${outDir}/genesis-key${pass ? '.enc' : ''}.b64`, backup);
+  writeFileSync(`${outDir}/ust-genesis`, JSON.stringify(genesis));
+  writeFileSync(`${outDir}/ust-keylog-0`, JSON.stringify(keylog0));
+  console.log(`       wrote ${outDir}/ust-genesis + ust-keylog-0 + genesis-key${pass ? '.enc' : ''}.b64  (COLD-STORE the key)`);
+  console.log('       self-check: genesis + key-log verify ✓');
+
+  // 3. DNS (profile A) — manual paste or CF one-click (upsert + DoH readback)
+  const txt = `ust-genesis=${genHash}`;
+  if (dns === 'cf-api') {
+    console.log('  3/5  writing _ust.' + domain + ' TXT via Cloudflare API (upsert + DoH readback)…');
+    let res; try { res = await cfUpsert({ domain, txt, genHash, token: process.env.CF_TOKEN || process.env.CLOUDFLARE_API_TOKEN }); }
+    catch (e) { rl.close(); die(e.message); }
+    console.log('       ✓ _ust TXT ' + res.action + ' and confirmed by DoH readback (Vercel-style, idempotent)');
+  } else {
+    console.log('  3/5  DNS (profile A, DNSSEC): add this TXT record, or skip for profile B (TLS-witness):');
+    console.log('       _ust.' + domain + '  TXT  "' + txt + '"');
+  }
+
+  // 4. publish well-known + fail-closed content-hash match
+  console.log('  4/5  publish this file at  https://' + domain + '/.well-known/ust-genesis');
+  console.log('       (the exact document in ' + outDir + '/ust-genesis)');
+  await ask('       press Enter once it is live… ');
+  try {
+    const live = await fetch(`https://${domain}/.well-known/ust-genesis`, { signal: AbortSignal.timeout(10000) }).then((r) => r.text());
+    checkPublished(live, genHash);
+    console.log('       ✓ well-known verifies and its content_hash matches (fail-closed)');
+  } catch (e) { rl.close(); die('could not confirm the published well-known: ' + e.message + '  (authoritative NOT granted — retry)'); }
+
+  // 5. witnesses + anchor — PREPARED here; the operator runs the exchange + anchor
+  const witnesses = (arg('witness', '') || '').split(',').filter(Boolean);
+  const [head, ...rest] = stageSummary({ genHash, witnesses, profile });
+  console.log('  5/5  ' + head);
+  for (const line of rest) console.log('       ' + line);
+
+  console.log('\n  ✓ GENESIS PREPARED — verified locally + at well-known');
+  console.log('    name           : ' + domain);
+  console.log('    genesis        : ' + genHash);
+  console.log('    operational    : ' + op.key_id + '  (daily key; genesis stays cold)');
+  console.log('    max_partitions : ' + (maxP ?? '(default floor 64)'));
+  console.log('    outputs        : ' + outDir + '/ust-genesis + ust-keylog-0  (two verifiable UST — `ust verify` them)');
+  console.log('    key backup     : ' + outDir + '/genesis-key' + (pass ? '.enc' : '') + '.b64  (encrypted PKCS#8, NOT a UST)');
+  console.log('                     → operator-managed split + cold storage (needed ~yearly to rotate/revoke)');
+  console.log('    NEXT (operator): run the witness exchange + queue the anchor to reach VALID:HIGH/TOP\n');
+  rl.close();
+}
+
+// Run the dispatcher ONLY when executed directly — importing this module (regression suite / Go-binding
+// harness) must not trigger the CLI or its process.exit.
+const isMain = (() => { try { return process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url); } catch { return false; } })();
+if (isMain) {
+  const cmd = process.argv[2];
+  const run = { verify: cmdVerify, canon: cmdCanon, genesis: cmdGenesis }[cmd];
+  if (!run) { console.error('ust — verify machine-readable state\n\n  ust verify <file|->        verify a transcript (exit 0 = VALID, 1 = not)\n  ust canon  <file|->        print canonical bytes + hash (cross-language diff)\n  ust genesis --domain <d>   run the HIGH genesis ceremony\n'); process.exit(cmd ? 1 : 0); }
+  run().catch((e) => die(e.message || String(e)));
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@ust-protocol/cli",
+  "version": "1.0.0-rc.2",
+  "description": "The reference `ust` CLI for UST (Universal State Transcript) 1.0 — verify a transcript, print canonical bytes for cross-language diffing, and run the HIGH genesis ceremony. One entrypoint; the Go binary reproduces this surface.",
+  "author": "THE LAB (https://thelab.md)",
+  "type": "module",
+  "bin": { "ust": "./index.mjs" },
+  "files": ["index.mjs", "LICENSE", "README.md"],
+  "keywords": ["ust", "cli", "verify", "genesis", "trust-infrastructure"],
+  "license": "Apache-2.0",
+  "engines": { "node": ">=20" },
+  "dependencies": {
+    "ust-protocol": "^1.0.0-rc.7",
+    "@ust-protocol/web-signer": "^1.0.0-rc.3"
+  },
+  "repository": { "type": "git", "url": "git+https://github.com/thelabmd/UST-Protocol.git", "directory": "packages/ust-cli" },
+  "homepage": "https://github.com/thelabmd/UST-Protocol/tree/main/packages/ust-cli#readme",
+  "bugs": "https://github.com/thelabmd/UST-Protocol/issues"
+}