@arcadiasystems/morse-cli 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@ 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.7.0] - 2026-09-09
+
+### Added
+
+- **`--upload-relay <url|auto>`** routes Walrus uploads through a relay instead of the direct fanout, with `MORSE_WALRUS_UPLOAD_RELAY` and a per-profile `uploadRelay` following the usual `flags > env > config > defaults` precedence. `auto` resolves to the canonical Mysten relay for the selected network, and is refused on localnet, which has none.
+
+  A direct upload pushes slivers to every storage node in the committee at once, 95 on mainnet. Networks that cannot sustain that burst fail with `NotEnoughBlobConfirmationsError` even when the nodes are healthy and far above write quorum, and until now the CLI had no way around it while the SDK did: `DefaultWalrusWriteAdapter.fromConfig` already accepted `uploadRelay`, the CLI just never offered a way to set it.
+
+  Opt-in rather than default: the direct path is free and trustless, the relay costs a tip and sees your bytes.
+- **`--max-tip <mist>`** and `MORSE_WALRUS_MAX_TIP` cap the relay's per-upload tip, defaulting to 10000000 MIST (0.01 SUI). Mainnet prices the tip linearly in encoded blob size, so an uncapped relay upload has no upper bound on what it charges; over the cap `@mysten/walrus` refuses before spending. A non-integer or negative cap is rejected outright rather than falling back to the default, so a typo cannot silently authorise an unbounded tip.
+- `config add` takes `--upload-relay` to persist the choice on a profile. The value is validated at add time the way `--network` already is, so `auto` on a network with no canonical relay is refused immediately rather than producing a profile that only fails the first time someone uploads. `config list` shows it in both the human and `--json` renderings.
+
+### Notes
+
+- The relay setting and its tip cap are carried raw through `resolveSettings` and only resolved on the Walrus write path. `resolveSettings` runs for every command, so parsing them eagerly would let a typo'd `MORSE_WALRUS_MAX_TIP` in a shell profile or CI environment break reads that never upload anything. A malformed cap fails the upload, not `publication get`.
+
+  Verified live: uploads through the relay succeed on both networks and round-trip byte for byte, a too-low `--max-tip` refuses before spending, and a malformed one is rejected at parse time.
+
+## [0.6.1] - 2026-09-09
+
+Picks up `@arcadiasystems/morse-sdk@0.6.0` and fixes a download regression it exposed. Upgrade if you use mainnet at all.
+
+### Fixed
+
+- **`file download` worked on no mainnet file, public or not.** `buildFileDownloadContext` constructed the Seal adapter eagerly, so once SDK 0.6.0 stopped pinning mainnet key servers, every download failed at context build with a Seal error before the file was even looked up. Downloading a public file never touches Seal, so the adapter is now built on first use and memoized, matching the lazy-signer pattern the same context already used. Regression covered in `test/program.test.ts` against the real context builder.
+- **Encrypted commands now explain themselves on mainnet.** They previously surfaced the SDK's `ConfigurationError`, whose advice ("pass seal.serverConfigs", "start from MAINNET_SEAL_COMMITTEE") names an API the CLI does not expose: there is no flag or env var for key servers, so on mainnet these commands cannot work at all. `entry add-encrypted`, `entry decrypt`, `file upload --encrypt` / `--recipient`, and file decryption now exit 2 with a message that says that and points at testnet or the SDK.
+- **`file upload --public` is not caught by that guard.** It shares the encrypt context but never encrypts, so `EncryptContext.seal` became a lazy factory too. Building the adapter eagerly there would have blocked public mainnet uploads the same way the eager build blocked public downloads. Both the refusal and the exemption are covered in `test/program.test.ts`.
+- **`file download` refused every public file, on every network.** The check asked whether the file had recipients, on the assumption that "a public file has no recipients". The Move contract auto-includes the owner on creation, so `members` is non-empty for every file that exists, public or not: a public file and an encrypted one both report exactly one member. The result was that `file upload --public` produced a file the CLI would not download, telling the user their plaintext was "unusable ciphertext" and pointing at `--raw`, which then wrote the correct bytes anyway.
+
+  Encryption is now determined by the Seal id prefix via the new `getRecipientFileSealPrefix` in SDK 0.7.0, which is the only reliable signal. This bug predates the mainnet work and shipped in 0.6.0 and earlier.
+
+  It escaped the tests because the download fixture defaulted to `members: []`, modelling an object the contract cannot produce. The fixture now carries a realistic owner-member, and a regression test covers a public file that has members.
+- Dependency moves to `@arcadiasystems/morse-sdk@^0.7.0`. The published 0.6.0 declared `^0.5.0`, which resolves to the SDK release whose mainnet Seal default could produce permanently unreadable ciphertext.
+
+### Known gaps
+
+- `file list` still needs `--indexer-url` on every network; public Sui fullnodes have retired the JSON-RPC event query it walks.
+- Encrypted mainnet stays blocked until Seal operator credentials are available and the CLI grows a way to pass them.
+
 ## [0.6.0] - 2026-09-09
 
 Mainnet support, consuming `@arcadiasystems/morse-sdk@0.5.0`. The Move contracts

package/README.md

@@ -6,8 +6,20 @@ 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.6.0. Mainnet and testnet are both supported; the command surface is
-> stable.
+> Status: v0.7.0. 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.
+>
+> Everything that does not encrypt works on both networks, including
+> `file upload --public`, `file download` of a public file, and the whole
+> publication, collection and entry surface. All of that is verified against
+> live mainnet, including a public upload and download round trip.
 >
 > **The Move contracts are unaudited.** On mainnet, gas and Walrus storage cost
 > real SUI and WAL, there is no faucet, and deletions are irreversible. Nothing
@@ -100,6 +112,8 @@ Environment variables (override the config file, overridden by flags):
 | --- | --- | --- |
 | `MORSE_PROFILE` | `--profile` | Profile to use. |
 | `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_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. |
@@ -134,6 +148,8 @@ Global options apply to every command and must appear before the subcommand
 | `--network <mainnet\|testnet\|localnet>` | Network to target (default: testnet). `localnet` needs a custom deployment. |
 | `-p, --profile <name>` | Config profile to use. |
 | `--rpc <url>` | Override the Sui RPC URL. |
+| `--upload-relay <url\|auto>` | Upload Walrus blobs through a relay instead of the direct fanout. `auto` picks the canonical relay for the network. Costs a tip per upload. |
+| `--max-tip <mist>` | Cap the relay's per-upload tip, in MIST (default: 10000000). |
 | `--json` | Machine-readable JSON on stdout. |
 | `-q, --quiet` | Suppress progress and informational output. |
 | `-y, --yes` | Assume yes for confirmation prompts. |
@@ -156,7 +172,7 @@ and `-C, --collection <name>`, both defaulting to the active context.
 
 | Command | Purpose |
 | --- | --- |
-| `config add <name> --network <net> [--rpc <url>]` | Create or update a profile. |
+| `config add <name> --network <net> [--rpc <url>] [--upload-relay <url\|auto>]` | Create or update a profile. |
 | `config list` | List profiles; `*` marks the default. |
 | `config use <name>` | Set the default profile. |
 | `config remove <name>` | Delete a profile. |
@@ -327,12 +343,49 @@ to fetch the full record per file (one read each) when you need them.
   created but not yet populated through the CLI; `entry add` refuses them.
 - There is no command to query Walrus blob storage expiry; `--epochs` sets the
   lease at upload time, but remaining lease time is not exposed by the SDK.
+- Encrypted commands do not work on mainnet, per the status note above. There
+  is no way to supply Seal key servers to the CLI; if you have credentials from
+  an operator, use the SDK directly for now.
 - `localnet` is accepted as a network but has no canonical deployment, so it
   fails at startup unless you point the SDK at your own package and registry.
 - `file list` walks a JSON-RPC event query that public Sui fullnodes have
   retired, so it needs `--indexer-url` pointing at a source that serves the same
   query. This affects testnet as well as mainnet.
 
+## When uploads fail: the upload relay
+
+A Walrus upload pushes slivers to every storage node in the committee at once,
+95 of them on mainnet. Networks that cannot sustain that burst fail with
+`NotEnoughBlobConfirmationsError` or "Unable to connect", **even when the nodes
+are healthy and far above write quorum**. If uploads fail while reads work, this
+is almost certainly why, and it is not a fault in your config.
+
+Route the upload through a relay and one connection replaces ~95:
+
+```sh
+morse --upload-relay auto file upload ./photo.jpg --public -n photo
+```
+
+`auto` resolves to Mysten's canonical relay for the selected network. Pass a URL
+instead to use a different operator, or persist it on a profile:
+
+```sh
+morse config add mainnet --network mainnet --upload-relay auto
+```
+
+Three things to know before reaching for it:
+
+- **It costs a tip per upload**, on top of WAL and gas. Mainnet prices it
+  linearly in encoded blob size; a small blob runs about 0.0026 SUI.
+- **The tip is capped** at `--max-tip` (default 10000000 MIST, 0.01 SUI). Over
+  the cap the upload is refused before anything is spent, rather than quietly
+  charging more than you expected.
+- **The relay sees your bytes.** Same trade as any hosted service; encrypt first
+  if that matters.
+
+It is opt-in on purpose. The direct path is free and trustless, and most
+networks handle it fine.
+
 ## Publishing
 
 Published to the public npm registry as the scoped package

package/dist/index.js

@@ -148,7 +148,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@arcadiasystems/morse-cli",
-  version: "0.6.0",
+  version: "0.7.0",
   description: "Command-line interface for the Morse decentralized CMS on Sui.",
   license: "MIT",
   type: "module",
@@ -203,7 +203,7 @@ var package_default = {
     prepublishOnly: "bun run check && bun run build"
   },
   dependencies: {
-    "@arcadiasystems/morse-sdk": "^0.5.0",
+    "@arcadiasystems/morse-sdk": "^0.7.0",
     "@mysten/seal": "1.1.3",
     "@mysten/sui": "2.16.2",
     "@mysten/walrus": "1.1.6",
@@ -217,9 +217,10 @@ var package_default = {
 };
 
 // src/cli/program.ts
+var DEFAULT_MAX_TIP_MIST = 1e7;
 function buildProgram() {
   const program = new Command;
-  program.name("morse").description("Command-line interface for the Morse decentralized CMS on Sui.").version(package_default.version, "-V, --version", "Print the version and exit").option("--network <network>", "Sui network: mainnet, testnet, or localnet [env: MORSE_NETWORK]").option("-p, --profile <name>", "Config profile to use [env: MORSE_PROFILE]").option("--rpc <url>", "Override the Sui RPC URL [env: MORSE_RPC_URL]").option("--json", "Output machine-readable JSON on stdout").option("-q, --quiet", "Suppress progress and informational output").option("-y, --yes", "Assume yes for confirmation prompts").option("--debug", "Print stack traces on error").enablePositionalOptions().showHelpAfterError().exitOverride();
+  program.name("morse").description("Command-line interface for the Morse decentralized CMS on Sui.").version(package_default.version, "-V, --version", "Print the version and exit").option("--network <network>", "Sui network: mainnet, testnet, or localnet [env: MORSE_NETWORK]").option("-p, --profile <name>", "Config profile to use [env: MORSE_PROFILE]").option("--rpc <url>", "Override the Sui RPC URL [env: MORSE_RPC_URL]").option("--upload-relay <url|auto>", "Upload Walrus blobs through a relay instead of fanning out to every storage node; 'auto' picks the canonical relay for the network. Costs a tip per upload [env: MORSE_WALRUS_UPLOAD_RELAY]").option("--max-tip <mist>", `Cap the per-upload relay tip, in MIST (default: ${DEFAULT_MAX_TIP_MIST}) [env: MORSE_WALRUS_MAX_TIP]`).option("--json", "Output machine-readable JSON on stdout").option("-q, --quiet", "Suppress progress and informational output").option("-y, --yes", "Assume yes for confirmation prompts").option("--debug", "Print stack traces on error").enablePositionalOptions().showHelpAfterError().exitOverride();
   return program;
 }
 
@@ -462,6 +463,9 @@ function parseProfile(name, value, source) {
   if (typeof value.rpc === "string") {
     profile.rpc = value.rpc;
   }
+  if (typeof value.uploadRelay === "string") {
+    profile.uploadRelay = value.uploadRelay;
+  }
   if (typeof value.account === "string") {
     profile.account = value.account;
   }
@@ -564,6 +568,35 @@ async function updateActiveProfile(opts, patch, env = process.env) {
 }
 
 // src/config/profile.ts
+function canonicalUploadRelay(network) {
+  if (network === "mainnet" || network === "testnet") {
+    return `https://upload-relay.${network}.walrus.space`;
+  }
+  return;
+}
+function resolveUploadRelay(value, network) {
+  if (value === undefined || value === "") {
+    return;
+  }
+  if (value !== "auto") {
+    return value;
+  }
+  const canonical = canonicalUploadRelay(network);
+  if (canonical === undefined) {
+    throw new UsageError(`--upload-relay auto has no canonical relay for ${network}. Pass an explicit relay URL.`);
+  }
+  return canonical;
+}
+function parseMaxTip(value) {
+  if (value === undefined || value === "") {
+    return DEFAULT_MAX_TIP_MIST;
+  }
+  const parsed = /^\d+$/.test(value) ? Number(value) : Number.NaN;
+  if (!Number.isSafeInteger(parsed)) {
+    throw new UsageError(`--max-tip must be a non-negative integer in MIST; got "${value}".`);
+  }
+  return parsed;
+}
 function resolveSettings(opts, config, env = process.env) {
   const explicitProfile = opts.profile ?? env.MORSE_PROFILE;
   const profileName = explicitProfile ?? config.defaultProfile;
@@ -574,10 +607,21 @@ function resolveSettings(opts, config, env = process.env) {
   const networkValue = opts.network ?? env.MORSE_NETWORK ?? profile?.network ?? "testnet";
   const network = coerceNetwork(networkValue);
   const rpcUrl = opts.rpc ?? env.MORSE_RPC_URL ?? profile?.rpc;
+  const uploadRelay = opts.uploadRelay ?? env.MORSE_WALRUS_UPLOAD_RELAY ?? profile?.uploadRelay;
+  const maxTip = opts.maxTip ?? env.MORSE_WALRUS_MAX_TIP;
   const account = env.MORSE_ADDRESS ?? profile?.account;
   const publication = env.MORSE_PUBLICATION ?? profile?.publication;
   const collection = env.MORSE_COLLECTION ?? profile?.collection;
-  return { profileName, network, rpcUrl, account, publication, collection };
+  return {
+    profileName,
+    network,
+    rpcUrl,
+    uploadRelay,
+    maxTip,
+    account,
+    publication,
+    collection
+  };
 }
 
 // src/keystore/keystore.ts
@@ -991,7 +1035,7 @@ async function buildContentContext(command) {
     throw new CliError("Walrus content uploads are not available on localnet. Use testnet or mainnet.", ExitCode.Usage);
   }
   const adapter = new KeypairAdapter(keypair, base.client);
-  const walrus = DefaultWalrusWriteAdapter.fromConfig({ network, suiClient: base.client }, keypair);
+  const walrus = DefaultWalrusWriteAdapter.fromConfig(walrusWriteConfig(base, network), keypair);
   return {
     ...base,
     output: base.output.withNetwork(network),
@@ -1000,10 +1044,26 @@ async function buildContentContext(command) {
     walrus
   };
 }
+function assertSealAvailable(config) {
+  if (config.sealKeyServers.length > 0) {
+    return;
+  }
+  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);
+}
+function walrusWriteConfig(base, network) {
+  const host = resolveUploadRelay(base.settings.uploadRelay, network);
+  if (host === undefined) {
+    return { network, suiClient: base.client };
+  }
+  return {
+    network,
+    suiClient: base.client,
+    uploadRelay: { host, sendTip: { max: parseMaxTip(base.settings.maxTip) } }
+  };
+}
 async function buildEncryptContext(command) {
   const ctx = await buildContentContext(command);
-  const seal = DefaultSealAdapter.fromMorseConfig(ctx.config, {}, ctx.client);
-  return { ...ctx, seal };
+  return { ...ctx, seal: lazySeal(ctx) };
 }
 function walrusReadAdapter(base, network, viaAggregator) {
   if (viaAggregator) {
@@ -1031,6 +1091,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);
   return {
     ...base,
@@ -1052,10 +1113,18 @@ async function buildFileDownloadContext(command, opts = {}) {
       packageId: base.config.packageId
     }),
     walrusRead: walrusReadAdapter(base, network, Boolean(opts.viaAggregator)),
-    seal: DefaultSealAdapter.fromMorseConfig(base.config, {}, base.client),
+    seal: lazySeal(base),
     unlockSigner: () => resolveSigner(base.settings.account, process.env, base.signal)
   };
 }
+function lazySeal(base) {
+  let adapter;
+  return () => {
+    assertSealAvailable(base.config);
+    adapter ??= DefaultSealAdapter.fromMorseConfig(base.config, {}, base.client);
+    return adapter;
+  };
+}
 async function buildFileListContext(command, opts = {}) {
   const base = await buildReadContext(command);
   const originPackageId = base.config.recipientFileEventOriginPackageId;
@@ -1525,12 +1594,14 @@ async function runConfigList(output) {
 }
 async function runConfigAdd(output, name, options) {
   const network = coerceNetwork(options.network);
+  resolveUploadRelay(options.uploadRelay, network);
   const cfg = await loadConfig();
   const profiles = {
     ...cfg.profiles,
     [name]: {
       network,
-      ...options.rpc === undefined ? {} : { rpc: options.rpc }
+      ...options.rpc === undefined ? {} : { rpc: options.rpc },
+      ...options.uploadRelay === undefined ? {} : { uploadRelay: options.uploadRelay }
     }
   };
   const defaultProfile = Object.keys(cfg.profiles).length === 0 ? name : cfg.defaultProfile;
@@ -1539,6 +1610,7 @@ async function runConfigAdd(output, name, options) {
     profile: name,
     network,
     rpc: options.rpc,
+    uploadRelay: options.uploadRelay,
     default: defaultProfile === name
   });
 }
@@ -1568,7 +1640,7 @@ function registerConfigCommands(program) {
   config.command("list").description("List profiles and show the default").action(async (_options, command) => {
     await runConfigList(outputFor(command));
   });
-  config.command("add <name>").description("Create or update a profile").requiredOption("--network <network>", "Sui network: mainnet, testnet, or localnet").option("--rpc <url>", "RPC URL override for this profile").action(async (name, options, command) => {
+  config.command("add <name>").description("Create or update a profile").requiredOption("--network <network>", "Sui network: mainnet, testnet, or localnet").option("--rpc <url>", "RPC URL override for this profile").option("--upload-relay <url|auto>", "Walrus upload relay for this profile; 'auto' picks the canonical relay for the network").action(async (name, options, command) => {
     await runConfigAdd(outputFor(command), name, options);
   });
   config.command("use <name>").description("Set the default profile").action(async (name, _options, command) => {
@@ -1598,6 +1670,9 @@ function renderProfiles(config) {
     if (profile.rpc !== undefined) {
       parts.push(profile.rpc);
     }
+    if (profile.uploadRelay !== undefined) {
+      parts.push(`relay=${profile.uploadRelay}`);
+    }
     if (profile.account !== undefined) {
       parts.push(profile.account);
     }
@@ -1681,7 +1756,7 @@ async function runEntryAddEncrypted(ctx, name, options) {
   ctx.output.info(`Encrypting and uploading ${plaintext.length} bytes...`);
   const result = await addEncryptedEntryFromBytes(ctx.adapter, ctx.config, {
     walrus: ctx.walrus,
-    seal: ctx.seal,
+    seal: ctx.seal(),
     publicationId: id,
     publisherCapId,
     collectionName: collection,
@@ -2168,7 +2243,7 @@ async function runFileUpload(ctx, path, options) {
   }
   const result = await uploadEncryptedRecipientFileFromBytes(ctx.adapter, ctx.config, {
     walrus: ctx.walrus,
-    seal: ctx.seal,
+    seal: ctx.seal(),
     plaintext: bytes,
     recipients,
     name: options.name,
@@ -2238,7 +2313,7 @@ async function decryptRecipientFile(ctx, fileId, ciphertext, prefix, nonce) {
     signer: keypair,
     suiClient: ctx.client
   });
-  return ctx.seal.decryptUnderRecipientFile(ciphertext, {
+  return ctx.seal().decryptUnderRecipientFile(ciphertext, {
     sessionKey,
     sealId,
     fileId
@@ -2254,9 +2329,10 @@ async function runFileDownload(ctx, positional, options) {
   }
   const fileId = toRecipientFileId(target.fileId);
   const file = await ctx.filesReader.getRecipientFile(fileId, ctx.signal);
-  if (target.decrypt === undefined && file.members.length > 0) {
+  const encrypted = target.decrypt !== undefined || await ctx.filesReader.getRecipientFileSealPrefix(fileId, ctx.signal) !== null;
+  if (target.decrypt === undefined && encrypted) {
     if (!options.raw) {
-      throw new UsageError("This file has a recipient list, so its bytes are encrypted. Pass --share (or --prefix and --nonce) to decrypt, or --raw to write the raw ciphertext anyway.");
+      throw new UsageError("This file is encrypted. Pass --share (or --prefix and --nonce) to decrypt, or --raw to write the raw ciphertext anyway.");
     }
     ctx.output.warn("Writing raw ciphertext (--raw); the output is unusable without decryption.");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arcadiasystems/morse-cli",
-	"version": "0.6.0",
+	"version": "0.7.0",
 	"description": "Command-line interface for the Morse decentralized CMS on Sui.",
 	"license": "MIT",
 	"type": "module",
@@ -55,7 +55,7 @@
 		"prepublishOnly": "bun run check && bun run build"
 	},
 	"dependencies": {
-		"@arcadiasystems/morse-sdk": "^0.5.0",
+		"@arcadiasystems/morse-sdk": "^0.7.0",
 		"@mysten/seal": "1.1.3",
 		"@mysten/sui": "2.16.2",
 		"@mysten/walrus": "1.1.6",