mnemonad-cli 0.1.0

package/lib/commands/shared.js

@@ -0,0 +1,385 @@
+import { mkdir, writeFile, readFile, readdir, rm } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { getAddress } from 'viem';
+import { MnemonadPinataProvider, kekMethodOf } from 'mnemonad';
+
+// monadsync re-exports its whole sync-primitives surface (see monadsync/index.js), so
+// these come from there rather than adding a second, lower-level dependency.
+import { DoubleSync as SyncEngine, CDCStore, DoubleSyncSnapshot as SyncSnapshot } from 'monadsync';
+import { FSFolder } from '../FSFolder.js';
+import { createPresignProvider } from '../presignProvider.js';
+
+const DEFAULT_FS_EXCLUDES = ['node_modules', '.git', '.env', '.DS_Store', '.mnemonad', '.claude', 'pnpm-lock.yaml', 'package-lock.json'];
+
+export function makeExcludes(args) {
+    if (!args.exclude) return undefined;
+    const extra = args.exclude.split(',').map(s => s.trim());
+    return [...DEFAULT_FS_EXCLUDES, ...extra];
+}
+
+/**
+ * Resolves how a writing command (push, watch, compact) offloads large items, as extra
+ * fields to spread into a `Mnemonad`/`Mnemonad.create` params object. Precedence:
+ *
+ *   1. `--pinata-jwt` — a direct Pinata credential, no signing needed. Goes through
+ *      `MnemonadPinataProvider` (not a bare `pinningJwt` field): the default `MnemonadIpfs`
+ *      Mnemonad would otherwise build needs an explicit `pinningUrl` too, which
+ *      `MnemonadPinataProvider` supplies — passing `pinningJwt` alone to the plain
+ *      constructor path silently never enables write capability at all.
+ *   2. `--presign-url` (or its config-file/env-var default — see bin/mnemonad.js) — no
+ *      credential needed; the account itself signs a request proving it paid the on-chain
+ *      escrow, and the presign server exchanges that for a one-shot upload URL (see
+ *      presign-server/README.md). Requires a signing `account` (the caller only reaches
+ *      this branch from a write path, which already has one).
+ *   3. Neither configured — just `gatewayUrl`, which is read-only: no offload capability at
+ *      all, so a push with an oversized item fails with a clear error instead of silently
+ *      falling back to something the caller didn't ask for.
+ *
+ * @param {Object} args - parsed CLI args
+ * @param {Object} account - viem account signing this command's writes
+ * @returns {{offloadingProvider: Object} | {gatewayUrl: ?string}}
+ */
+export function resolveOffloadParams(args, account) {
+    if (args.pinataJwt) {
+        return { offloadingProvider: new MnemonadPinataProvider({ pinningJwt: args.pinataJwt, gatewayUrl: args.gatewayUrl }) };
+    }
+    if (args.presignUrl) {
+        return { offloadingProvider: createPresignProvider({ presignUrl: args.presignUrl, gatewayUrl: args.gatewayUrl, account }) };
+    }
+    return { gatewayUrl: args.gatewayUrl };
+}
+
+/**
+ * Resolves a folder path argument. Deliberately does NOT fall back to `process.cwd()` when
+ * `p` is missing — every command that touches a folder requires the caller to name it
+ * explicitly, so a typo'd or omitted `path` never silently operates on whatever directory
+ * the CLI happened to be run from.
+ */
+export function resolvePath(p) {
+    if (!p) {
+        const err = new Error('a folder path is required (e.g. `mnemonad <command> ... /path/to/folder`)');
+        err._isUserError = true;
+        throw err;
+    }
+    if (p.startsWith('~')) return join(homedir(), p.slice(1));
+    return resolve(p);
+}
+
+export function formatBytes(bytes) {
+    if (bytes < 1024) return bytes + ' B';
+    if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + ' KB';
+    return (bytes / (1024 * 1024)).toFixed(1) + ' MB';
+}
+
+export function formatPath(path) {
+    const home = homedir();
+    if (path.startsWith(home)) {
+        return '~' + path.slice(home.length);
+    }
+    return path;
+}
+
+/**
+ * Address that owns the stream, or null when it can't be determined (RPC failure, or the
+ * stream doesn't exist yet — `ownerOf` on a nonexistent token id reverts).
+ */
+export async function getStreamOwner(mn) {
+    try {
+        return await mn.owner();
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Fail before any push when the signer doesn't own the stream — otherwise on-chain storage
+ * (and any IPFS pin) gets paid for and only the final write is rejected. Stays quiet when
+ * ownership can't be determined and lets the chain decide.
+ *
+ * An EVM address comparison via viem's `getAddress` (checksum-normalizes both sides) is all
+ * that's needed here.
+ */
+export async function assertStreamOwner(mn, signerAddress) {
+    const owner = await getStreamOwner(mn);
+    if (!owner || !signerAddress) return;
+    if (getAddress(owner) === getAddress(signerAddress)) return;
+
+    const err = new Error(
+        `stream ${mn.id} is owned by ${owner}\n` +
+        `  but you are signing as ${signerAddress}.\n` +
+        `  Nothing was uploaded. Use the owner's key (--key / --phrase / MNEMONAD_KEY),\n` +
+        `  or run push without a stream id to create your own stream.`
+    );
+    err._isUserError = true;
+    throw err;
+}
+
+/**
+ * Decides how a NEW stream should be keyed, from the encryption flags given.
+ *
+ * `--encrypt` alone is rejected rather than guessed at: both methods are reachable from the
+ * same invocation (the `--key` account can always sign), and picking one silently would
+ * decide, unprompted, whether the stream is recoverable by a password or bound forever to
+ * whatever key happened to be in the environment.
+ *
+ * @param {Object} args - parsed CLI args
+ * @returns {?('password'|'wallet')} `null` when the stream should stay unencrypted
+ */
+export function resolveEncryptMethod(args) {
+    const requested = args.encryptWith || (args.password ? 'password' : null);
+
+    if (!args.encrypt) {
+        if (args.encryptWith) {
+            throw userError('--encrypt-with needs --encrypt (it only applies when creating a stream)');
+        }
+        return null;
+    }
+    if (!requested) {
+        throw userError(
+            '--encrypt needs a method: --encrypt-with password (with --password), or\n' +
+            '  --encrypt-with wallet to key it to the --key/--phrase account\'s signature'
+        );
+    }
+    if (requested !== 'password' && requested !== 'wallet') {
+        throw userError(`unknown --encrypt-with '${requested}', expected password or wallet`);
+    }
+    if (requested === 'password' && !args.password) {
+        throw userError('--encrypt-with password needs --password');
+    }
+    if (requested === 'wallet' && args.password) {
+        throw userError(
+            '--encrypt-with wallet takes no --password — a wallet-keyed stream is unwrapped by\n' +
+            '  the owner\'s signature, and the two methods cannot both key one stream'
+        );
+    }
+    return requested;
+}
+
+/**
+ * Unlocks `mn` for reading/writing an encrypted stream, whichever way it was keyed.
+ *
+ * Which credential to try comes from the stream's own published `kek` block via
+ * `kekMethodOf` — but only as a *hint*: stream metadata is written once at creation and can
+ * never be corrected, while the owner can rewrap under a different method at any time. The
+ * GCM tag on the wrapped key is the authority, and a mismatch surfaces as the SDK's typed
+ * `KEK_MISMATCH` error either way.
+ *
+ * Neither credential is ever passed to the `Mnemonad` constructor here. For a password that
+ * would silently derive a key from a *fresh* salt instead of the stream's published one, and
+ * every later read/write would fail deep inside decryption (or, worse, succeed and wrap a
+ * key nothing else can ever unwrap). `unlockWithPassword`/`unlockWithSignature` are the only
+ * paths that read what the stream actually published.
+ *
+ * @param {import('mnemonad').default} mn
+ * @param {Object} [credentials]
+ * @param {?string} [credentials.password]
+ * @param {?Object} [credentials.signer] - viem WalletClient/Account, for a wallet-keyed stream
+ * @returns {Promise<boolean>} whether the stream was encrypted (and, if so, is now unlocked)
+ */
+export async function unlockStream(mn, credentials = {}) {
+    const { password = null, signer = null } = credentials;
+
+    await mn.initialize();
+    if (!(await mn.isEncrypted())) return false;
+
+    const method = kekMethodOf({ kek: mn.streamMeta.kek, encrypted: true });
+
+    if (method === 'password') {
+        if (!password) {
+            throw userError('This stream is encrypted with a password. Provide --password to decrypt.');
+        }
+        await mn.unlockWithPassword(password);
+        return true;
+    }
+
+    // 'signature' — including every stream created before the method marker existed, which
+    // published no kek block at all.
+    if (!signer) {
+        throw userError(
+            'This stream is encrypted to its owner\'s wallet. Provide the owner\'s key with\n' +
+            '  --key / --phrase / MNEMONAD_KEY to decrypt it.'
+        );
+    }
+    await mn.unlockWithSignature(signer);
+    return true;
+}
+
+function userError(message) {
+    const err = new Error(message);
+    err._isUserError = true;
+    return err;
+}
+
+export async function countTree(folder) {
+    let files = 0;
+    let folders = 0;
+    const children = await folder.list();
+    for (const child of children) {
+        if (child.getContent) {
+            files++;
+        } else {
+            folders++;
+            const sub = await countTree(child);
+            files += sub.files;
+            folders += sub.folders;
+        }
+    }
+    return { files, folders };
+}
+
+export function hashContent(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+
+export async function readManifest(destPath) {
+    try {
+        const raw = await readFile(join(destPath, '.mnemonad'), 'utf8');
+        return JSON.parse(raw);
+    } catch { return null; }
+}
+
+export async function writeManifest(destPath, manifest) {
+    await writeFile(join(destPath, '.mnemonad'), JSON.stringify(manifest, null, 2));
+}
+
+export const DISK_EXCLUDES = new Set(['.mnemonad', '.git', '.DS_Store', 'node_modules']);
+
+export async function hashDiskTree(dirPath, prefix = []) {
+    const files = {};
+    let entries;
+    try { entries = await readdir(dirPath, { withFileTypes: true }); } catch { return files; }
+    for (const entry of entries) {
+        if (DISK_EXCLUDES.has(entry.name) || entry.name.startsWith('.')) continue;
+        const relParts = [...prefix, entry.name];
+        const relPath = relParts.join('/');
+        const fullPath = join(dirPath, entry.name);
+        if (entry.isFile()) {
+            const buf = await readFile(fullPath);
+            files[relPath] = hashContent(buf);
+        } else if (entry.isDirectory()) {
+            Object.assign(files, await hashDiskTree(fullPath, relParts));
+        }
+    }
+    return files;
+}
+
+export async function localTreeHash(dirPath) {
+    const fsFolder = new FSFolder(dirPath);
+    const children = await fsFolder.list();
+    if (children.length === 0) return null;
+
+    const sync = new SyncEngine();
+    const store = new CDCStore();
+    const snapshotBytes = await sync.buildSnapshot({ root: fsFolder, store });
+    return new SyncSnapshot(snapshotBytes).treeHash;
+}
+
+export async function syncMemoryFolderToDisk(folder, destPath, oldFiles) {
+    const newFiles = {};
+    const newDirs = new Set();
+    const stats = { written: 0, skipped: 0, deleted: 0, folders: 0, bytes: 0 };
+
+    // walkAndSync only mkdir's a child directory as it descends into it — a root-level file
+    // (no subfolder ever created first) would otherwise fail to write into a destPath that
+    // doesn't exist yet, e.g. the very first `pull` into a brand-new directory.
+    await mkdir(destPath, { recursive: true });
+    await walkAndSync(folder, destPath, [], oldFiles, newFiles, newDirs, stats);
+
+    if (oldFiles) {
+        for (const relPath of Object.keys(oldFiles)) {
+            if (!(relPath in newFiles)) {
+                const absPath = join(destPath, ...relPath.split('/'));
+                await rm(absPath, { force: true });
+                stats.deleted++;
+            }
+        }
+    }
+
+    await removeStaleDirectories(destPath, newDirs);
+
+    return { stats, newFiles };
+}
+
+export function hashMapsEqual(a, b) {
+    const keysA = Object.keys(a).sort();
+    const keysB = Object.keys(b).sort();
+    if (keysA.length !== keysB.length) return false;
+    return keysA.every((k, i) => k === keysB[i] && a[k] === b[k]);
+}
+
+export async function hashLocalTree(fsFolder, prefix = []) {
+    const files = {};
+    const children = await fsFolder.list();
+    for (const child of children) {
+        const relParts = [...prefix, child.name];
+        const relPath = relParts.join('/');
+        if (child.getContent) {
+            const content = await child.getContent();
+            files[relPath] = hashContent(content);
+        } else {
+            Object.assign(files, await hashLocalTree(child, relParts));
+        }
+    }
+    return files;
+}
+
+async function walkAndSync(folder, destPath, prefix, oldFiles, newFiles, newDirs, stats) {
+    const children = await folder.list();
+
+    for (const child of children) {
+        const relParts = [...prefix, child.name];
+        const relPath = relParts.join('/');
+        const absPath = join(destPath, child.name);
+
+        if (child.getContent) {
+            const content = await child.getContent();
+            const hash = hashContent(content);
+            newFiles[relPath] = hash;
+
+            if (oldFiles && oldFiles[relPath] === hash) {
+                stats.skipped++;
+            } else {
+                await writeFile(absPath, content);
+                stats.written++;
+                stats.bytes += content.length;
+            }
+        } else {
+            await mkdir(absPath, { recursive: true });
+            newDirs.add(relPath);
+            stats.folders++;
+            await walkAndSync(child, absPath, relParts, oldFiles, newFiles, newDirs, stats);
+        }
+    }
+}
+
+async function removeStaleDirectories(destPath, newDirs) {
+    let entries;
+    try { entries = await readdir(destPath, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        if (DISK_EXCLUDES.has(entry.name) || entry.name.startsWith('.')) continue;
+        const fullPath = join(destPath, entry.name);
+        if (!newDirs.has(entry.name)) {
+            await rm(fullPath, { recursive: true, force: true });
+        } else {
+            await removeStaleSubdirs(fullPath, entry.name, newDirs);
+        }
+    }
+}
+
+async function removeStaleSubdirs(dirPath, prefix, newDirs) {
+    let entries;
+    try { entries = await readdir(dirPath, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const relPath = prefix + '/' + entry.name;
+        const fullPath = join(dirPath, entry.name);
+        if (!newDirs.has(relPath)) {
+            await rm(fullPath, { recursive: true, force: true });
+        } else {
+            await removeStaleSubdirs(fullPath, relPath, newDirs);
+        }
+    }
+}

package/lib/commands/watch.js

@@ -0,0 +1,183 @@
+import { watch as fsWatch } from 'node:fs';
+import Mnemonad from 'mnemonad';
+import { MonadSync } from 'monadsync';
+import { FSFolder } from '../FSFolder.js';
+import { makeChainClient, requireWalletClient } from '../chainClient.js';
+import {
+    resolvePath,
+    makeExcludes,
+    formatPath,
+    localTreeHash,
+    hashDiskTree,
+    syncMemoryFolderToDisk,
+    DISK_EXCLUDES,
+    assertStreamOwner,
+    unlockStream,
+    resolveOffloadParams,
+} from './shared.js';
+
+function timestamp() {
+    return new Date().toTimeString().slice(0, 8);
+}
+
+function hashesEqual(a, b) {
+    if (a === null && b === null) return true;
+    if (a === null || b === null) return false;
+    return a.length === b.length && a.every((byte, i) => byte === b[i]);
+}
+
+export async function watch(args) {
+    if (!args.streamId) throw new Error('stream-id is required for watch');
+
+    const cwd = resolvePath(args.path);
+    const debounceMs = args.debounce ?? 5000;
+    const pollIntervalMs = (args.pollInterval ?? 2) * 1000;
+    const pushEnabled = !args.pullOnly;
+    const pullEnabled = !args.pushOnly;
+
+    const excludes = makeExcludes(args);
+
+    const client = makeChainClient(args);
+    if (pushEnabled) requireWalletClient(client);
+
+    // Only a push-enabled session needs write-side offload capability (pinata-jwt or
+    // presign) — a pull-only mirror only ever reads, so it gets just gatewayUrl.
+    const offloadParams = pushEnabled ? resolveOffloadParams(args, client.account) : { gatewayUrl: args.gatewayUrl };
+
+    // No `password` at construction — see shared.js's unlockStream() for why; unlocked
+    // explicitly right below instead, once for the whole watch session.
+    const mn = new Mnemonad({
+        publicClient: client.publicClient,
+        walletClient: pushEnabled ? client.walletClient : undefined,
+        contractAddress: client.contractAddress,
+        id: args.streamId,
+        ...offloadParams,
+    });
+
+    await unlockStream(mn, { password: args.password, signer: client.walletClient });
+
+    // Fail now rather than on the first local change, hours into a watch session.
+    if (pushEnabled) {
+        await assertStreamOwner(mn, client.account.address);
+    }
+
+    const monadSync = new MonadSync({ mnemonad: mn, compress: args.compress || 'gzip' });
+    await monadSync.initialize();
+
+    let remoteVersion = mn.length;
+    let lastSyncedHash = await localTreeHash(cwd);
+    let pushInFlight = false;
+    let debounceTimer = null;
+
+    console.log(`watching ${formatPath(cwd)}`);
+    console.log(`  stream:        ${args.streamId}`);
+    console.log(`  remote version: ${remoteVersion}`);
+    console.log(`  push:          ${pushEnabled ? `enabled (debounce ${debounceMs}ms)` : 'disabled'}`);
+    console.log(`  pull:          ${pullEnabled ? `enabled (poll every ${pollIntervalMs / 1000}s)` : 'disabled'}`);
+    console.log('press Ctrl+C to stop\n');
+
+    async function runPush() {
+        if (!pushEnabled || pushInFlight) return;
+        const newHash = await localTreeHash(cwd);
+        if (hashesEqual(newHash, lastSyncedHash)) return;
+
+        pushInFlight = true;
+        try {
+            // Best-effort race guard, not an atomic one: Mnemonad's own contract has no
+            // "expected prior length" check — no atomic on-chain compare-and-abort.
+            // Re-checking here narrows the window where a concurrent push (another `watch`
+            // session, or a manual push) could make MonadSync build a diff against a base
+            // the chain has since moved past — the same failure mode monadsync's own
+            // snapshot-recovery tests exercise — but doesn't close it entirely; only an
+            // on-chain guard could.
+            mn.reInitialize();
+            await mn.initialize();
+            if (mn.length !== remoteVersion) {
+                console.log(`[${timestamp()}] remote changed while preparing push — resyncing before pushing`);
+                monadSync.reInitialize();
+                await monadSync.initialize();
+                remoteVersion = mn.length;
+            }
+
+            const fsFolder = new FSFolder(cwd, excludes);
+            console.log(`[${timestamp()}] change detected — pushing...`);
+            const result = await monadSync.push(fsFolder);
+            lastSyncedHash = newHash;
+            remoteVersion = result.version;
+            console.log(`[${timestamp()}] pushed version ${result.version}`);
+        } catch (err) {
+            console.error(`[${timestamp()}] push error:`, err.message);
+        } finally {
+            pushInFlight = false;
+        }
+    }
+
+    async function runPoll() {
+        if (!pullEnabled || pushInFlight) return;
+        try {
+            mn.reInitialize();
+            await mn.initialize();
+            if (mn.length <= remoteVersion) return;
+
+            const newRemoteVersion = mn.length;
+
+            // Always resync monadSync when remote has advanced. Without this, its own
+            // internal snapshot/replay state stays at the old version while mn.length has
+            // moved on — the next push would build a diff against the wrong base,
+            // corrupting the chain.
+            monadSync.reInitialize();
+
+            const localNow = await localTreeHash(cwd);
+
+            if (!hashesEqual(localNow, lastSyncedHash)) {
+                console.log(`[${timestamp()}] remote has ${newRemoteVersion - remoteVersion} new version(s) but local has unpushed changes — skipping pull`);
+                return;
+            }
+
+            console.log(`[${timestamp()}] remote advanced to version ${newRemoteVersion} — pulling...`);
+            let folder;
+            try {
+                folder = await monadSync.restore();
+            } catch (err) {
+                console.error(`[${timestamp()}] pull failed (${err.message}) — skipping to version ${newRemoteVersion}; run \`pull\` manually`);
+                remoteVersion = newRemoteVersion;
+                return;
+            }
+            const oldFiles = await hashDiskTree(cwd);
+            const { stats } = await syncMemoryFolderToDisk(folder, cwd, oldFiles);
+            lastSyncedHash = await localTreeHash(cwd);
+            remoteVersion = newRemoteVersion;
+            console.log(`[${timestamp()}] pulled version ${remoteVersion} (${stats.written} written, ${stats.skipped} unchanged, ${stats.deleted} deleted)`);
+        } catch (err) {
+            console.error(`[${timestamp()}] poll error:`, err.message);
+        }
+    }
+
+    const watcher = fsWatch(cwd, { recursive: true }, (eventType, filename) => {
+        if (!pushEnabled) return;
+        if (!filename) return;
+        const base = filename.split('/')[0];
+        if (DISK_EXCLUDES.has(base) || base.startsWith('.')) return;
+        clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(runPush, debounceMs);
+    });
+
+    const poller = setInterval(runPoll, pollIntervalMs);
+
+    let shutdownResolve;
+    const shutdownPromise = new Promise((resolve) => {
+        shutdownResolve = resolve;
+    });
+
+    function shutdown() {
+        console.log('\nstopping watch...');
+        clearTimeout(debounceTimer);
+        clearInterval(poller);
+        watcher.close();
+        shutdownResolve();
+    }
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+
+    await shutdownPromise;
+}

package/lib/presignProvider.js

@@ -0,0 +1,83 @@
+/**
+ * Node/viem port of explorer/src/mnemonad/presignProvider.js's `createPresignProvider`.
+ *
+ * Same off-chain-upload flow, same server (see `presign-server/README.md`'s diagram): a
+ * paid on-chain escrow (handled automatically by Mnemonad's own `push()` — see
+ * `Mnemonad._pushExternalAuto`) is proven with an EIP-712 signature, the server checks it
+ * against the escrow and hands back a one-shot Pinata upload URL. No Pinata credential ever
+ * touches this process, unlike `--pinata-jwt`.
+ *
+ * The only real difference from the browser version: the explorer signs with `wagmi`'s
+ * `signTypedData` against a connected wallet; here the CLI already holds a local viem
+ * account (from `chainClient.js`), and viem's local accounts sign EIP-712 data directly via
+ * `account.signTypedData(...)` — no wallet client or connected extension needed.
+ */
+import { MnemonadPresignProvider } from 'mnemonad';
+
+const SIGNATURE_TTL_SECONDS = 120;
+
+/**
+ * @param {Object} params
+ * @param {string} params.presignUrl - base URL of the presign server (no trailing slash)
+ * @param {string} params.gatewayUrl - public IPFS gateway for reads (same one every other
+ *   read path in this CLI uses — see chainClient.js's own default)
+ * @param {import('viem/accounts').LocalAccount} params.account - signs the upload request;
+ *   must be the same address that paid the on-chain escrow (`payer` in the signed message)
+ * @returns {MnemonadPresignProvider}
+ */
+export function createPresignProvider({ presignUrl, gatewayUrl, account }) {
+    const baseUrl = presignUrl.replace(/\/$/, '');
+    let configPromise = null;
+
+    function fetchConfig() {
+        if (!configPromise) {
+            configPromise = fetch(`${baseUrl}/config`)
+                .then(async (res) => {
+                    if (!res.ok) throw new Error(`presign server /config failed (HTTP ${res.status})`);
+                    return await res.json();
+                })
+                .catch((err) => {
+                    configPromise = null; // don't cache a failure — the server may just be starting
+                    throw err;
+                });
+        }
+        return configPromise;
+    }
+
+    return new MnemonadPresignProvider({
+        gatewayUrl,
+        requestUploadUrl: async ({ hash, size }) => {
+            const serverConfig = await fetchConfig();
+            const deadline = Math.floor(Date.now() / 1000) + SIGNATURE_TTL_SECONDS;
+
+            // Signed with the domain/types the server published, not a local copy — see
+            // presign-server/README.md's own reasoning for why (drift between two hardcoded
+            // copies would eventually produce signature failures that look like account bugs).
+            const signature = await account.signTypedData({
+                domain: serverConfig.eip712.domain,
+                types: serverConfig.eip712.types,
+                primaryType: serverConfig.eip712.primaryType,
+                message: {
+                    payer: account.address,
+                    contentHash: hash,
+                    size: BigInt(size),
+                    deadline: BigInt(deadline),
+                },
+            });
+
+            const res = await fetch(`${baseUrl}/upload-url`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ payer: account.address, contentHash: hash, size, deadline, signature }),
+            });
+
+            const body = await res.json().catch(() => ({}));
+            if (!res.ok) {
+                // The server's error codes are actionable (e.g. "no_escrow" means the payment
+                // step was skipped) — surface its message rather than a generic failure.
+                throw new Error(body.message || `presign server refused the upload (HTTP ${res.status})`);
+            }
+            return { url: body.url };
+        },
+    });
+}

package/mnemonad.config.js

@@ -0,0 +1,21 @@
+/**
+ * Project-wide operational defaults for the CLI — non-secret URLs only, safe to commit.
+ * Never put a key or JWT in here: those stay in `--key`/`MNEMONAD_KEY`/`PINATA_JWT`, which
+ * this file has no bearing on.
+ *
+ * Precedence bin/mnemonad.js applies for every value here: CLI flag > env var > this file >
+ * a hardcoded fallback (kept in case this file goes missing or fails to parse).
+ */
+export default {
+    // The presign server (../presign-server/) this project runs by default — see its own
+    // README for what it does. Pushing an item too big to fit on-chain (over the registry's
+    // maxChunkBytes) uses this automatically, so a signer needs no Pinata credential of
+    // their own. Overridable per-run with --presign-url or MNEMONAD_PRESIGN_URL.
+    presignUrl: 'https://presign-server.vercel.app',
+
+    // Public IPFS gateway for *reading* externally-offloaded items (pull/diff/info/watch)
+    // — same default the explorer dApp uses (explorer/src/mnemonad/presignProvider.js), so
+    // a stream pushed through either tool reads back the same way with no setup. Overridable
+    // per-run with --gateway-url or MNEMONAD_IPFS_GATEWAY.
+    gatewayUrl: 'https://gateway.pinata.cloud/ipfs/',
+};