@arcadiasystems/morse-cli 0.9.0 → 0.10.1

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to `@arcadiasystems/morse-cli` are documented here. The
 format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.10.1] - 2026-09-10
+
+Tooling only. No behaviour changes.
+
+### Added
+
+- `bun run docs-gate`, wired into `bun run check` alongside the coverage gate. It fails when the README status banner does not name the current version, or when CHANGELOG's newest entry does not match `package.json`. The banner silently claimed v0.3.0 for two whole releases, and nothing in lint, typecheck, tests or coverage could catch it.
+
+## [0.10.0] - 2026-09-10
+
+### Added
+
+- **Encrypted commands work on mainnet when you bring a Seal credential.** Mainnet pins no key servers because every operator there is commercial, and the CLI previously had no way to be pointed at one, so `entry add-encrypted`, `entry decrypt` and `file upload --encrypt` simply could not run there.
+
+  `MORSE_SEAL_API_KEY` supplies a credential for Mysten's committee, whose object id and aggregator the SDK already exports; `MORSE_SEAL_API_KEY_NAME` overrides the header for operators that want something other than `X-API-Key`. `MORSE_SEAL_KEY_SERVERS` takes a JSON array of `{ objectId, weight }` for a non-committee operator and wins when both are set. Neither is a flag: a credential in argv leaks through `ps` and shell history, the same reason the signing key is not one.
+
+- **The credential is checked before anything is encrypted.** Seal reads key-server public keys from chain but fetches key shares from the operator, so a wrong credential would let `encrypt` succeed and fail only at `decrypt`, leaving the user paying to store content nobody can read. That exact shape shipped once as the mainnet Seal default, and an unchecked API key would have reintroduced it user-side. Only an explicit `401` or `403` refuses; any other outcome, including the check being unreachable, proceeds, because a flaky pre-flight must never block a working key.
+
+  Verified live: a full encrypt and decrypt round trip on testnet through `MORSE_SEAL_KEY_SERVERS` (the same code path a credential takes), and a bogus `MORSE_SEAL_API_KEY` refused against the real Mysten aggregator with the pre-flight message rather than producing unreadable ciphertext.
+
 ## [0.9.0] - 2026-09-10
 ### Fixed (config state, found in a whole-package bug hunt)
 

package/README.md

@@ -6,15 +6,14 @@ content entries from your terminal, signing with a locally encrypted key.
 Content is stored on [Walrus](https://walrus.xyz); private entries are encrypted
 with [Seal](https://github.com/MystenLabs/seal).
 
-> Status: v0.9.0. Mainnet and testnet are both supported for public content;
+> Status: v0.10.1. Mainnet and testnet are both supported for public content;
 > the command surface is stable.
 >
-> **Encrypted commands are testnet-only.** `entry add-encrypted`, `entry
-> decrypt`, `file upload --encrypt` (and `--recipient`, which implies it), and
-> decrypting a downloaded file all need Seal key servers. Testnet has an open
-> set; mainnet does not, because every mainnet Seal operator is commercial, and
-> the CLI has no flag or env var for supplying one. These commands exit 2 on
-> mainnet with an explanation.
+> **Encrypted commands need Seal key servers.** Testnet has an open set, so
+> they work there out of the box. Mainnet has none, because every mainnet Seal
+> operator is commercial: supply your own credential via `MORSE_SEAL_API_KEY`
+> (see [Seal on mainnet](#seal-on-mainnet)), or these commands exit 2 with an
+> explanation.
 >
 > Everything that does not encrypt works on both networks, including
 > `file upload --public`, `file download` of a public file, and the whole
@@ -114,6 +113,9 @@ Environment variables (override the config file, overridden by flags):
 | `MORSE_NETWORK` | `--network` | `mainnet`, `testnet`, or `localnet`. |
 | `MORSE_WALRUS_UPLOAD_RELAY` | `--upload-relay` | Upload through a Walrus relay instead of the direct fanout. `auto` picks the canonical relay for the network. |
 | `MORSE_WALRUS_MAX_TIP` | `--max-tip` | Cap the relay's per-upload tip, in MIST. Defaults to 10000000 (0.01 SUI). |
+| `MORSE_SEAL_API_KEY` | (none) | Credential for Mysten's Seal committee, enabling encrypted commands on mainnet. |
+| `MORSE_SEAL_API_KEY_NAME` | (none) | Header name for that credential. Defaults to `X-API-Key`. |
+| `MORSE_SEAL_KEY_SERVERS` | (none) | JSON array of `{ objectId, weight }` for a non-committee Seal operator. Wins over `MORSE_SEAL_API_KEY`. |
 | `MORSE_RPC_URL` | `--rpc` | Sui RPC URL override. |
 | `MORSE_ADDRESS` | (no flag) | Active account address, selecting which keystore to use. |
 | `MORSE_PUBLICATION` | `-P, --publication` | Active publication id. |
@@ -372,6 +374,41 @@ for works. These are aliases, not separate commands:
 
 `publication` also answers to `pub`.
 
+## Seal on mainnet
+
+Encrypted commands need Seal key servers. Testnet pins an open set, so they
+work there with no setup. Mainnet pins none: every mainnet Seal operator is
+commercial, so you bring your own.
+
+The usual route is a credential for Mysten's decentralized committee, which
+the CLI already knows the object id and aggregator for:
+
+```sh
+export MORSE_SEAL_API_KEY=your-key-here
+morse --network mainnet file upload ./secret.pdf --encrypt -r 0xrecipient
+```
+
+For an operator that is not the committee, give the servers directly:
+
+```sh
+export MORSE_SEAL_KEY_SERVERS='[{"objectId":"0x...","weight":1}]'
+```
+
+Entries may carry `aggregatorUrl`, `apiKeyName` and `apiKey`; Seal requires
+`aggregatorUrl` on a committee-mode server and forbids it on an independent
+one. `MORSE_SEAL_KEY_SERVERS` takes precedence when both are set.
+
+**Neither is a flag, deliberately.** A credential in argv leaks through `ps`
+and shell history, the same reason the signing key is never a flag either.
+
+Before encrypting anything, the CLI checks the credential against the operator
+and refuses if it comes back `401` or `403`. This matters more than it looks:
+Seal reads key-server public keys from chain but fetches key *shares* from the
+operator, so a bad credential would let encryption succeed and fail only at
+decryption, leaving you paying to store content nobody can ever read. Any other
+outcome, including the check being offline, proceeds normally, because a flaky
+check must never block a working key.
+
 ## When uploads fail: the upload relay
 
 A Walrus upload pushes slivers to every storage node in the committee at once,

package/dist/index.js

@@ -148,7 +148,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@arcadiasystems/morse-cli",
-  version: "0.9.0",
+  version: "0.10.1",
   description: "Command-line interface for the Morse decentralized CMS on Sui.",
   license: "MIT",
   type: "module",
@@ -191,6 +191,7 @@ var package_default = {
     start: "bun src/index.ts",
     build: "bun build src/index.ts --target node --packages external --outfile dist/index.js",
     typecheck: "tsc --noEmit",
+    "docs-gate": "bun scripts/docs-gate.ts",
     lint: "biome check .",
     "lint:fix": "biome check --write .",
     test: "bun test",
@@ -199,11 +200,11 @@ var package_default = {
     "test:coverage": "bun test --coverage",
     "test:e2e": "MORSE_E2E=1 bun test test/e2e/",
     coverage: "bun scripts/coverage-gate.ts",
-    check: "tsc --noEmit && biome check . && bun scripts/coverage-gate.ts",
+    check: "tsc --noEmit && biome check . && bun scripts/docs-gate.ts && bun scripts/coverage-gate.ts",
     prepublishOnly: "bun run check && bun run build"
   },
   dependencies: {
-    "@arcadiasystems/morse-sdk": "^0.8.0",
+    "@arcadiasystems/morse-sdk": "^0.8.1",
     "@mysten/seal": "1.1.3",
     "@mysten/sui": "2.16.2",
     "@mysten/walrus": "1.1.6",
@@ -989,6 +990,72 @@ import {
 } from "@arcadiasystems/morse-sdk";
 import { SuiGrpcClient } from "@mysten/sui/grpc";
 
+// src/config/seal.ts
+import { MAINNET_SEAL_COMMITTEE } from "@arcadiasystems/morse-sdk";
+var DEFAULT_API_KEY_NAME = "X-API-Key";
+function sealServersFromEnv(env = process.env) {
+  const explicit = env.MORSE_SEAL_KEY_SERVERS;
+  if (explicit !== undefined && explicit.length > 0) {
+    return { servers: parseKeyServers(explicit) };
+  }
+  const apiKey = env.MORSE_SEAL_API_KEY;
+  if (apiKey === undefined || apiKey.length === 0) {
+    return;
+  }
+  const apiKeyName = env.MORSE_SEAL_API_KEY_NAME ?? DEFAULT_API_KEY_NAME;
+  return {
+    servers: MAINNET_SEAL_COMMITTEE.map((server) => ({
+      ...server,
+      apiKeyName,
+      apiKey
+    })),
+    ...MAINNET_SEAL_COMMITTEE[0]?.aggregatorUrl === undefined ? {} : { verifyUrl: MAINNET_SEAL_COMMITTEE[0].aggregatorUrl },
+    apiKeyName,
+    apiKey
+  };
+}
+async function assertSealCredentialAccepted(env, fetchImpl = fetch) {
+  if (env.verifyUrl === undefined || env.apiKey === undefined) {
+    return;
+  }
+  let status;
+  try {
+    const response = await fetchImpl(`${env.verifyUrl}/v1/service`, {
+      headers: { [env.apiKeyName ?? DEFAULT_API_KEY_NAME]: env.apiKey }
+    });
+    status = response.status;
+  } catch {
+    return;
+  }
+  if (status === 401 || status === 403) {
+    throw new UsageError(`The Seal operator at ${env.verifyUrl} rejected your credential (HTTP ${status}). Encrypting anyway would produce content you could never decrypt, so this stops here. Check MORSE_SEAL_API_KEY.`);
+  }
+}
+function parseKeyServers(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (cause) {
+    throw new UsageError(`MORSE_SEAL_KEY_SERVERS is not valid JSON: ${String(cause)}`);
+  }
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    throw new UsageError('MORSE_SEAL_KEY_SERVERS must be a non-empty JSON array of { objectId, weight } entries, e.g. [{"objectId":"0x...","weight":1}].');
+  }
+  return parsed.map((entry, index) => {
+    if (typeof entry !== "object" || entry === null) {
+      throw new UsageError(`MORSE_SEAL_KEY_SERVERS[${index}] is not an object.`);
+    }
+    const { objectId, weight } = entry;
+    if (typeof objectId !== "string" || !objectId.startsWith("0x")) {
+      throw new UsageError(`MORSE_SEAL_KEY_SERVERS[${index}].objectId must be a 0x-prefixed object id.`);
+    }
+    if (typeof weight !== "number" || !Number.isInteger(weight) || weight < 1) {
+      throw new UsageError(`MORSE_SEAL_KEY_SERVERS[${index}].weight must be a positive integer.`);
+    }
+    return entry;
+  });
+}
+
 // src/cli/graphql-events.ts
 function canonicalGraphqlUrl(network) {
   if (network === "mainnet" || network === "testnet") {
@@ -1114,11 +1181,12 @@ async function buildContentContext(command) {
     walrus
   };
 }
-function assertSealAvailable(config) {
-  if (config.sealKeyServers.length > 0) {
-    return;
+function buildSeal(config, client) {
+  const fromEnv = sealServersFromEnv();
+  if (fromEnv === undefined && config.sealKeyServers.length === 0) {
+    throw new CliError(`Encrypted commands are not available on ${config.network}: it pins no Seal key servers, because every operator there is commercial. Set MORSE_SEAL_API_KEY if you have a credential for Mysten's committee, or MORSE_SEAL_KEY_SERVERS to a JSON array for another operator. Otherwise use --network testnet.`, ExitCode.Usage);
   }
-  throw new CliError(`Encrypted commands are not available on ${config.network}. Seal key servers there are operated commercially and the CLI cannot yet be pointed at one. Use --network testnet, or drive @arcadiasystems/morse-sdk directly with your own seal.serverConfigs.`, ExitCode.Usage);
+  return DefaultSealAdapter.fromMorseConfig(config, fromEnv === undefined ? {} : { serverConfigs: fromEnv.servers }, client);
 }
 function walrusWriteConfig(base, network) {
   const host = resolveUploadRelay(base.settings.uploadRelay, network);
@@ -1133,6 +1201,10 @@ function walrusWriteConfig(base, network) {
 }
 async function buildEncryptContext(command) {
   const ctx = await buildContentContext(command);
+  const fromEnv = sealServersFromEnv();
+  if (fromEnv !== undefined) {
+    await assertSealCredentialAccepted(fromEnv);
+  }
   return { ...ctx, seal: lazySeal(ctx) };
 }
 function walrusReadAdapter(base, network, viaAggregator) {
@@ -1161,8 +1233,7 @@ async function buildDecryptContext(command, opts = {}) {
   if (network === "localnet") {
     throw new CliError("Seal decryption is not available on localnet. Use testnet or mainnet.", ExitCode.Usage);
   }
-  assertSealAvailable(base.config);
-  const seal = DefaultSealAdapter.fromMorseConfig(base.config, {}, base.client);
+  const seal = buildSeal(base.config, base.client);
   return {
     ...base,
     keypair,
@@ -1190,8 +1261,7 @@ async function buildFileDownloadContext(command, opts = {}) {
 function lazySeal(base) {
   let adapter;
   return () => {
-    assertSealAvailable(base.config);
-    adapter ??= DefaultSealAdapter.fromMorseConfig(base.config, {}, base.client);
+    adapter ??= buildSeal(base.config, base.client);
     return adapter;
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arcadiasystems/morse-cli",
-	"version": "0.9.0",
+	"version": "0.10.1",
 	"description": "Command-line interface for the Morse decentralized CMS on Sui.",
 	"license": "MIT",
 	"type": "module",
@@ -43,6 +43,7 @@
 		"start": "bun src/index.ts",
 		"build": "bun build src/index.ts --target node --packages external --outfile dist/index.js",
 		"typecheck": "tsc --noEmit",
+		"docs-gate": "bun scripts/docs-gate.ts",
 		"lint": "biome check .",
 		"lint:fix": "biome check --write .",
 		"test": "bun test",
@@ -51,11 +52,11 @@
 		"test:coverage": "bun test --coverage",
 		"test:e2e": "MORSE_E2E=1 bun test test/e2e/",
 		"coverage": "bun scripts/coverage-gate.ts",
-		"check": "tsc --noEmit && biome check . && bun scripts/coverage-gate.ts",
+		"check": "tsc --noEmit && biome check . && bun scripts/docs-gate.ts && bun scripts/coverage-gate.ts",
 		"prepublishOnly": "bun run check && bun run build"
 	},
 	"dependencies": {
-		"@arcadiasystems/morse-sdk": "^0.8.0",
+		"@arcadiasystems/morse-sdk": "^0.8.1",
 		"@mysten/seal": "1.1.3",
 		"@mysten/sui": "2.16.2",
 		"@mysten/walrus": "1.1.6",