@xgamesfun/solana 0.27.1 → 0.28.0

package/README.md

@@ -8,8 +8,8 @@
 [![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.XGamesFun%2Fsolana--kit-8a2be2)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.XGamesFun/solana-kit)
 
 You describe your game's or community's economy in a small JSON file: what players buy, open, stake, win or craft.
-The tools check it, show you where the money goes, tell you what it costs, and then you put it live by approving it in
-your own wallet. It runs on **loot**, one Solana program that every project shares, so there is no Anchor or Rust to
+The tools check it, show you where the money goes, tell you what it costs, and then it goes live, signed on your own
+computer once you have read what will be sent and said yes. It runs on **loot**, one Solana program that every project shares, so there is no Anchor or Rust to
 write, deploy or audit yourself.
 
 Most people never touch the JSON: they ask an AI agent (Claude Code, Codex, Cursor, ChatGPT or Claude) for _"a fishing
@@ -39,8 +39,20 @@ Every move leaves a public receipt on chain. Random rolls come from MagicBlock's
 1. **Describe it.** In a sentence to your agent, or as a spec file (`xsolana.json`).
 2. **Check it.** `check` refuses anything the program would refuse; `simulate` shows where the money goes, day by
    day; `cost` prices going live and each player action; `review` shows what a cheater could get.
-3. **Approve it.** A page opens on your own computer, lists every transaction, and you approve them in your wallet.
-   Nothing here ever signs for you or asks for a key.
+3. **Put it live.** `approve` lists every transaction with what it pays and trusts, ends with a code, and sends
+   nothing; run again with that code, it sends exactly what it listed. A key file on your own computer signs
+   (`keygen` makes one for the project). Nothing here asks for a seed phrase or for the key of a wallet you already
+   have, and no page opens unless you ask for your browser wallet.
+
+**Why a key file and not a browser wallet?** A key file made for the project is a new key that has never held
+anything else, so the wallet that holds what you own is never connected or asked to sign; it signs each transaction
+exactly as it was prepared and shown; and nothing opens in your browser. What it costs: the key is a plain file, so
+anything on your machine that can read it can sign as the project. It is the project's owner, for good (these tools
+can't hand a project to another owner), so keep it like one: outside any repository (the tools refuse one inside,
+unless git ignores it there), never pasted anywhere, and backed up by you, because nothing restores a lost one.
+Unless your spec names a `treasury`, what the economy earns for you lands at the key's address: name a wallet you
+hold (`"treasury": "wallet:<address>"`) before going live. To sign in a browser wallet instead, `approve --browser`
+serves the page for it.
 
 New here? The [loot box tutorial](docs/tutorial-loot-box.md) walks through all three with real output.
 
@@ -64,7 +76,7 @@ codex plugin add xsolana@xgamesfun
 
 **claude.ai, ChatGPT or Claude Desktop:** add `https://xgames.fun/mcp` as a custom connector. Nothing to install.
 
-**Cursor, Cline, opencode or any MCP client:** run `npx -y --package=@xgamesfun/solana@0.27.1 xsolana mcp`.
+**Cursor, Cline, opencode or any MCP client:** run `npx -y --package=@xgamesfun/solana@0.28.0 xsolana mcp`.
 
 **Any agent that reads skills** (Copilot, Gemini CLI, Windsurf…): `npx skills add XGamesFun/solana-kit`.
 
@@ -75,22 +87,26 @@ are in [docs/harnesses.md](docs/harnesses.md).
 
 ```bash
 # find a worked example close to your idea
-npx -y @xgamesfun/solana@0.27.1 examples shop with loot boxes
+npx -y @xgamesfun/solana@0.28.0 examples shop with loot boxes
 
 # using a coin you already launched? read it from the chain into its "tokens" entry
-npx -y @xgamesfun/solana@0.27.1 token <its mint address>
+npx -y @xgamesfun/solana@0.28.0 token <its mint address>
 
 # does it work? where does the money go? what does it cost?
-npx -y @xgamesfun/solana@0.27.1 check xsolana.json
-npx -y @xgamesfun/solana@0.27.1 simulate xsolana.json
-npx -y @xgamesfun/solana@0.27.1 cost xsolana.json
+npx -y @xgamesfun/solana@0.28.0 check xsolana.json
+npx -y @xgamesfun/solana@0.28.0 simulate xsolana.json
+npx -y @xgamesfun/solana@0.28.0 cost xsolana.json
 
 # the whole economy in plain words, and what a cheater could get
-npx -y @xgamesfun/solana@0.27.1 explain xsolana.json
-npx -y @xgamesfun/solana@0.27.1 review xsolana.json
-
-# go live, approved in your own wallet
-npx -y @xgamesfun/solana@0.27.1 approve xsolana.json
+npx -y @xgamesfun/solana@0.28.0 explain xsolana.json
+npx -y @xgamesfun/solana@0.28.0 review xsolana.json
+
+# go live: a key file for the project (it prints the address to send devnet SOL to, never the key)…
+npx -y @xgamesfun/solana@0.28.0 keygen ~/.config/xsolana/my-game.json
+# …then everything going live would send, and a code; nothing is sent
+npx -y @xgamesfun/solana@0.28.0 approve xsolana.json --keypair ~/.config/xsolana/my-game.json
+# …and with that code, exactly what it listed is sent
+npx -y @xgamesfun/solana@0.28.0 approve xsolana.json --keypair ~/.config/xsolana/my-game.json --yes <code>
 ```
 
 Each command names an exact version, so you always run the release you meant to. `xsolana help` lists them all.
@@ -122,6 +138,7 @@ module covers buying, opening boxes, staking, crafting, tickets, bids and claims
 | `@xgamesfun/solana/client`       | one builder per instruction, every address, account and receipt decoders              |
 | `@xgamesfun/solana/sponsor`      | your server pays players' fees (never their price), so players with no SOL can play   |
 | `@xgamesfun/solana/results`      | results and vouchers your game's server signs                                         |
+| `@xgamesfun/solana/keyfile`      | the project's key file as a signer, for a script of the owner's own steps (Node)      |
 | `@xgamesfun/solana`              | the tools themselves: `check`, `simulate`, `cost`, `review`, `explainEconomy`, `plan` |
 | `@xgamesfun/solana/mcp/http`     | the MCP server as a web handler, to host it yourself                                  |
 | `@xgamesfun/solana/chain/*`      | small browser-safe Solana building blocks: base58, Borsh, transactions, tokens, Core  |
@@ -132,7 +149,7 @@ Using `@solana/kit`? `loot.toKitInstruction(ix)` turns any builder's instruction
 
 ## Good to know
 
-- **Devnet only, not yet audited.** Use a devnet wallet. Mainnet waits for an independent audit.
+- **Devnet only, not yet audited.** Mainnet waits for an independent audit.
 - **Upgrades can mean setting up again.** No program version so far has carried accounts over. Pin the package version.
 - **Players trust the project.** Your keys can mint and move your project's pools. The program protects players from
   each other and from mistakes, not from the project they chose.
@@ -147,7 +164,7 @@ built yet: read the [known limits](docs/program.md#known-limits) before promisin
 ## Questions
 
 **How do I make a loot box or gacha on Solana without writing a smart contract?** Describe it as a box (its price,
-its outcomes and their odds), run `check` and `simulate`, then `approve` it in your wallet. If the randomness oracle
+its outcomes and their odds), run `check` and `simulate`, then `approve` it with your project's key file. If the randomness oracle
 never answers, the buyer can get a refund. See the [tutorial](docs/tutorial-loot-box.md) and the
 [examples](examples).
 

package/bin/xsolana.mjs

@@ -8,7 +8,9 @@
 //   xsolana examples [words…] [--json]   the nearest worked examples and rated economies
 //   xsolana check|simulate|cost|explain|review|publish|status [file] [--json]   one tool on a spec file (default xsolana.json)
 //   xsolana token <mint> [--json]         a token made elsewhere, read from the chain: its `tokens` entry, powers and all
-//   xsolana approve [file] [--port n] [--no-open]   open the local page where the owner approves going live in their wallet
+//   xsolana keygen <file>                 make a key file for a project's owner (outside any repository; the key is never printed)
+//   xsolana approve [file] --keypair <keyfile> [--yes <code>]   put the economy live, signed by a key file: no browser, no page
+//   xsolana approve [file] --browser [--port n] [--no-open]     the same in a browser wallet, on a local page: only when the person asks for it
 //   xsolana connect [--agent claude|codex] [--scope user|project] [--local] [--remove] [--dry-run]   register the MCP server and the skill
 //   xsolana tool --list | xsolana tool <name> '<json>' [--args-file f] [--json]   any tool by name
 //   xsolana version
@@ -29,7 +31,9 @@ const USAGE = `xsolana: the tools for loot, one shared Solana program for game a
   xsolana explain [file]          the economy in plain words
   xsolana review [file]           what a cheater gets on each route, and what to fix before going live
   xsolana publish [file]          what going live does, and how to approve it
-  xsolana approve [file]          approve going live in your own wallet (a local page; --port n, --no-open)
+  xsolana keygen <file>           make a key file for the project’s owner, outside any repository (prints its address, never the key)
+  xsolana approve [file] --keypair <keyfile>   what going live sends, then (--yes <code>) send it, signed by that key file
+  xsolana approve [file] --browser             the same on a local page, signed in a browser wallet (--port n, --no-open)
   xsolana status [file]           a live economy on chain
   xsolana token <mint>            a token made elsewhere, as the chain has it: its "tokens" entry, with what its mint can do
   xsolana connect                 add the xsolana tools to Claude Code or Codex (--agent claude|codex, --scope user|project, --local, --remove, --dry-run)
@@ -45,7 +49,7 @@ const USAGE = `xsolana: the tools for loot, one shared Solana program for game a
 class UsageError extends Error {}
 
 /** The flags that take a value: `--name value` or `--name=value`. */
-const VALUED = new Set(['--args-file', '--agent', '--scope', '--port', '--host']);
+const VALUED = new Set(['--args-file', '--agent', '--scope', '--port', '--host', '--keypair', '--yes']);
 /** The flags each command takes; any other is refused. */
 const TOOL_FLAGS = ['--json'];
 const FLAGS = {
@@ -60,7 +64,8 @@ const FLAGS = {
   publish: TOOL_FLAGS,
   status: TOOL_FLAGS,
   token: TOOL_FLAGS,
-  approve: ['--port', '--no-open'],
+  keygen: [],
+  approve: ['--keypair', '--yes', '--browser', '--port', '--no-open'],
   connect: ['--agent', '--scope', '--local', '--remove', '--dry-run'],
   tool: ['--list', '--args-file', ...TOOL_FLAGS],
   version: [],
@@ -73,12 +78,16 @@ function parseArgs(rest) {
   const positional = [];
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
-    if (!a.startsWith('--') || a === '--') {
+    // (a bare -- is the shell's own end of flags, not a file's name)
+    if (a === '--') continue;
+    if (!a.startsWith('--')) {
       positional.push(a);
       continue;
     }
     const eq = a.indexOf('=');
     const name = eq > 0 ? a.slice(0, eq) : a;
+    if (VALUED.has(name) && flags.has(name)) throw new UsageError(`${name} is given twice: give it once.`);
+    if (eq > 0 && !VALUED.has(name)) throw new UsageError(`${name} takes no value: write it alone, or leave it out.`);
     flags.add(name);
     if (eq > 0) values.set(name, a.slice(eq + 1));
     else if (VALUED.has(name)) {
@@ -90,7 +99,17 @@ function parseArgs(rest) {
   return { flags, values, positional };
 }
 
-/** The port `xsolana approve` listens on: a whole number from 1 to 65535, or undefined for any free one. */
+/** What `xsolana approve` says when it is not told how the setup is signed. */
+const HOW_TO_SIGN = `xsolana approve: say how going live is signed.
+
+  --keypair <keyfile>   a key file on this machine signs (the usual way: no browser, no page). It shows everything that
+                        would be sent, with a code, and sends nothing; run again with --yes <code>, it sends exactly
+                        that. \`xsolana keygen <file>\` makes a new project's key file; one that is live is signed
+                        only by the key it went live with.
+  --browser             a browser wallet signs, on a page this command serves on this machine until it is live. Only
+                        when the person whose economy it is asks for that; they run it themselves.`;
+
+/** The port `xsolana approve --browser` listens on: a whole number from 1 to 65535, or undefined for any free one. */
 function portOf(value) {
   if (value === undefined) return undefined;
   const n = Number(value);
@@ -153,10 +172,56 @@ async function main(argv) {
       if (!positional[0]) throw new UsageError('xsolana token <mint>: give the token’s mint address.');
       await tool('xsolana_token', { mint: positional[0] });
       break;
+    case 'keygen': {
+      if (!positional[0])
+        throw new UsageError(
+          'xsolana keygen <file>: say where the key file goes, outside any repository (for example ~/.config/xsolana/my-game.json).',
+        );
+      if (positional.length > 1)
+        throw new UsageError(
+          'xsolana keygen <file> makes one key file: give one path (in quotes when it has a space).',
+        );
+      const { makeKeyFile } = await import('../js/approve/keyfile.mjs');
+      const { PACKAGE_VERSION } = await import('../js/mcp/tools.mjs');
+      const made = await makeKeyFile(positional[0]);
+      // The file as it was named when that is the home folder's (`~/…` reads the same in any shell), else whole; in
+      // quotes when a shell would split it.
+      const named = positional[0].startsWith('~') ? positional[0] : made.file;
+      const word = /^[\w./~:\\-]+$/.test(named) ? named : `"${named}"`;
+      console.log(
+        [
+          `A new key is in ${made.file}${process.platform === 'win32' ? '' : ', readable by you alone'}. Its address:`,
+          `  ${made.address}`,
+          'Whatever is set up with it, it owns, for good: anyone who can read that file controls the project, and every later change is signed by it. Keep the file where it is and never paste it into a chat, a spec, a repository or a page. Back it up yourself (a USB stick, a password manager): if it is lost, nothing can change the project or move what its address holds.',
+          `It holds nothing yet. Send it devnet SOL (\`xsolana cost\` says what going live takes; https://faucet.solana.com gives some), then: npx -y @xgamesfun/solana@${PACKAGE_VERSION} approve xsolana.json --keypair ${word}`,
+        ].join('\n'),
+      );
+      break;
+    }
     case 'approve': {
+      const file = positional[0] ?? 'xsolana.json';
+      const keyFile = values.get('--keypair');
+      const page = flags.has('--browser');
+      if (keyFile !== undefined && page)
+        throw new UsageError('--keypair and --browser are two ways to sign: give one.');
+      if (keyFile !== undefined) {
+        if (flags.has('--port') || flags.has('--no-open'))
+          throw new UsageError('--port and --no-open go with --browser.');
+        const { approveWithKey } = await import('../js/approve/with-key.mjs');
+        // It shows, and sends only when given the code of what it showed: it never stops to ask.
+        const r = await approveWithKey({ file, keyFile, yes: values.get('--yes') ?? null });
+        if (!r.ok) process.exitCode = 1;
+        break;
+      }
+      if (flags.has('--yes')) throw new UsageError('--yes goes with --keypair.');
+      if (!page) {
+        console.error(HOW_TO_SIGN);
+        process.exitCode = 1;
+        break;
+      }
       const port = portOf(values.get('--port'));
       const { approve } = await import('../js/approve/server.mjs');
-      await approve({ file: positional[0] ?? 'xsolana.json', port, open: !flags.has('--no-open') });
+      await approve({ file, port, open: !flags.has('--no-open') });
       break;
     }
     case 'connect': {

package/js/approve/details.mjs

@@ -120,7 +120,7 @@ function readDetails(reads, names) {
   for (const read of reads) {
     if (read?.unreadable) {
       lines.push(
-        `This step could not be read back (${read.unreadable}): check what it pays in your wallet before approving`,
+        `This step could not be read back (${read.unreadable}): nothing here shows what it pays, so don’t say yes to it until it reads back (in a browser wallet, check what the wallet shows)`,
       );
       continue;
     }

package/js/approve/keyfile.mjs

@@ -0,0 +1,242 @@
+// A key file: one Solana key on this machine, in the Solana CLI's own format (a JSON array of 64 numbers: the 32-byte
+// seed, then the public key). `xsolana keygen` makes one for a project and `xsolana approve --keypair` signs that
+// project's setup with it, so going live needs no browser wallet and no page. The key is the project's owner:
+// whoever can read the file controls the project. So a key file is only ever made new (never written over), readable
+// by its user alone, kept outside any git repository, and never printed: these functions hand back its address and a
+// way to sign, not its bytes.
+import { execFile } from 'node:child_process';
+import { createPrivateKey, createPublicKey, generateKeyPairSync, sign } from 'node:crypto';
+import { chmod, lstat, mkdir, open, readFile, realpath, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { encodeBase58 } from '../chain/base58.js';
+import { readTransaction, wireTransaction } from '../chain/tx.js';
+
+const PKCS8_ED25519 = Buffer.from('302e020100300506032b657004220420', 'hex');
+/** The most a key file holds: 64 numbers of up to three digits, with room for however it was spaced. */
+const MOST_BYTES = 4096;
+
+/** A refusal about a key file: said in one line, and it never quotes what the file holds. */
+export class KeyFileError extends Error {}
+
+/** `file` as a whole path: a leading `~` is the home folder, whether or not a shell expanded it. */
+export function keyFilePath(file) {
+  const text = String(file ?? '');
+  if (!text) throw new KeyFileError('Say which key file: a path outside any repository.');
+  if (text === '~') return homedir();
+  return path.resolve(text.startsWith('~/') || text.startsWith('~\\') ? path.join(homedir(), text.slice(2)) : text);
+}
+
+/** The key a 32-byte seed makes: { address, publicKey, sign(message), drop() }. The private key stays in here. */
+function keyOf(seed) {
+  let key = createPrivateKey({ key: Buffer.concat([PKCS8_ED25519, Buffer.from(seed)]), format: 'der', type: 'pkcs8' });
+  const publicKey = new Uint8Array(Buffer.from(createPublicKey(key).export({ format: 'jwk' }).x, 'base64url'));
+  return {
+    address: encodeBase58(publicKey),
+    publicKey,
+    sign(message) {
+      if (!key) throw new Error('This key was dropped.');
+      return new Uint8Array(sign(null, Buffer.from(message), key));
+    },
+    /** The key signs nothing more. */
+    drop() {
+      key = null;
+    },
+  };
+}
+
+const exists = p =>
+  stat(p).then(
+    () => true,
+    () => false,
+  );
+
+/** The nearest folder at or above `dir` that holds a `.git` (a repository's work tree, as far as a look can tell). */
+async function gitFolderAbove(dir) {
+  for (let at = dir; ; at = path.dirname(at)) {
+    if (await exists(path.join(at, '.git'))) return at;
+    if (path.dirname(at) === at) return null;
+  }
+}
+
+/** The environment git is asked in: the caller's, without its own git settings (GIT_DIR and the like), which would answer for another repository. */
+const gitEnv = () => ({
+  ...Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith('GIT_'))),
+  LC_ALL: 'C',
+  LANGUAGE: 'C',
+});
+
+/** git run in `root`: { code, stderr }, `code` 0 when it succeeded, its exit code otherwise, 'ENOENT' with no git. */
+const git = (root, args, run = execFile) =>
+  new Promise(resolve => {
+    const done = (error, _stdout, stderr) =>
+      resolve({ code: error ? (error.code ?? 1) : 0, stderr: String(stderr ?? '') });
+    try {
+      run('git', ['-C', root, ...args], { timeout: 10_000, env: gitEnv() }, done);
+    } catch (e) {
+      done(e);
+    }
+  });
+
+/**
+ * What git says of `file` in the folder `root`, which holds a `.git`: 'ignored' (never committed), 'kept' (it would
+ * be), 'none' (that `.git` is no repository: an empty folder of that name), or 'unknown' (git could not be asked, or
+ * the `.git` is a file, a worktree's or a submodule's pointer, that git can't follow: a repository whose own folder
+ * is away for now).
+ */
+async function gitSays(root, file, run) {
+  const asked = await git(root, ['check-ignore', '-q', '--', file], run);
+  if (asked.code === 0) return 'ignored';
+  if (asked.code === 1) return 'kept';
+  if (asked.code === 'ENOENT') return 'unknown';
+  const repository = await git(root, ['rev-parse', '--git-dir'], run);
+  if (repository.code === 0 || !/not a git repository/i.test(repository.stderr)) return 'unknown';
+  const pointer = await lstat(path.join(root, '.git')).then(
+    i => !i.isDirectory(),
+    () => false,
+  );
+  return pointer ? 'unknown' : 'none';
+}
+
+/** The nearest folder at or above `dir` that exists. */
+async function nearest(dir) {
+  for (let at = dir; ; at = path.dirname(at)) {
+    if ((await exists(at)) || path.dirname(at) === at) return at;
+  }
+}
+
+/**
+ * Refuses a key file inside a git repository's work tree, unless git ignores it there: a key in a repository is
+ * committed sooner or later, and a commit is for good. `from` is a folder that exists, at or above the file's own;
+ * `real` is the file's whole path with every link followed (the file itself need not exist yet). When git can't be
+ * asked, a `.git` above the file is taken at its word.
+ */
+async function outsideRepositories(shown, from, real, { run } = {}) {
+  for (let root = await gitFolderAbove(from); root;) {
+    const says = await gitSays(root, real, run);
+    if (says === 'ignored') return;
+    if (says !== 'none')
+      throw new KeyFileError(
+        `${shown} is inside the git repository at ${root}: a key there is committed sooner or later, and whoever reads it controls the project. Keep it outside any repository, for example ~/.config/xsolana/<name>.json.`,
+      );
+    // (a `.git` that is no repository: the folders above it are still asked)
+    root = path.dirname(root) === root ? null : await gitFolderAbove(path.dirname(root));
+  }
+}
+
+/** What the bytes of a key file hold: its key, or a refusal that quotes none of it. */
+function parseKey(file, text) {
+  const not = () =>
+    new KeyFileError(
+      `${file} is not a Solana key file (a JSON array of 64 numbers, as \`xsolana keygen\` and \`solana-keygen\` write).`,
+    );
+  let bytes;
+  try {
+    bytes = JSON.parse(text);
+  } catch {
+    throw not();
+  }
+  if (!Array.isArray(bytes) || bytes.length !== 64 || !bytes.every(b => Number.isInteger(b) && b >= 0 && b <= 255))
+    throw not();
+  const key = keyOf(Uint8Array.from(bytes.slice(0, 32)));
+  if (!key.publicKey.every((b, i) => b === bytes[32 + i])) {
+    key.drop();
+    throw new KeyFileError(
+      `${file} is damaged: its second half is not the public key of its first. Nothing was signed with it.`,
+    );
+  }
+  return key;
+}
+
+/**
+ * Makes a new key and writes it to `file`, which must not exist: the folder is made if need be (for its user alone),
+ * the file is readable and writable by its user alone, and a path inside a git repository is refused. Returns
+ * { file, address }: the whole path and the key's address, never the key.
+ * @param {string} file
+ * @param {{ run?: Function }} [options] `run`: how git is run (for tests).
+ */
+export async function makeKeyFile(file, { run } = {}) {
+  const target = keyFilePath(file);
+  const dir = path.dirname(target);
+  // (asked before a folder is made: nothing is left behind in a repository that is refused)
+  const base = await nearest(dir);
+  const from = await realpath(base);
+  await outsideRepositories(target, from, path.join(from, path.relative(base, target)), { run });
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  const { privateKey, publicKey } = generateKeyPairSync('ed25519');
+  const seed = Buffer.from(privateKey.export({ format: 'jwk' }).d, 'base64url');
+  const pub = Buffer.from(publicKey.export({ format: 'jwk' }).x, 'base64url');
+  let handle;
+  try {
+    // (`wx`: made new or not at all, so a key already there is never written over)
+    handle = await open(target, 'wx', 0o600);
+  } catch (e) {
+    if (e.code !== 'EEXIST') throw e;
+    const address = await readKeyFile(target, { run }).then(
+      k => {
+        k.drop();
+        return k.address;
+      },
+      () => null,
+    );
+    throw new KeyFileError(
+      address
+        ? `${target} is already there: a key file whose address is ${address}. Nothing was written. Use it, or name another file.`
+        : `${target} is already there, and nothing is ever written over: name another file.`,
+    );
+  }
+  try {
+    await handle.writeFile(`${JSON.stringify([...seed, ...pub])}\n`);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await chmod(target, 0o600);
+  seed.fill(0);
+  return { file: target, address: encodeBase58(new Uint8Array(pub)) };
+}
+
+/**
+ * Reads the key in `file` to sign with: { file, address, sign(message), signTransaction(wire), drop() }, which is
+ * also what `@xgamesfun/solana/play` takes as a wallet. Refused: a file other users of the machine can read, one
+ * inside a git repository, and anything that is not a whole key. No refusal quotes the file.
+ * @param {string} file
+ * @param {{ run?: Function, platform?: string }} [options] `run`: how git is run; `platform`: the system's name (for tests).
+ */
+export async function readKeyFile(file, { run, platform = process.platform } = {}) {
+  const target = keyFilePath(file);
+  let info;
+  try {
+    info = await stat(target);
+  } catch (e) {
+    if (e.code === 'ENOENT')
+      throw new KeyFileError(
+        `${target} does not exist. A new project’s key file is made with \`xsolana keygen\`; a project that is live is signed only by the key it went live with.`,
+      );
+    throw e;
+  }
+  if (!info.isFile()) throw new KeyFileError(`${target} is not a file.`);
+  if (info.size > MOST_BYTES) throw new KeyFileError(`${target} is too big to be a Solana key file.`);
+  if (platform !== 'win32' && info.mode & 0o077)
+    throw new KeyFileError(
+      `${target} can be read by other users of this machine (its mode is ${(info.mode & 0o777).toString(8)}). Run: chmod 600 ${target}`,
+    );
+  const real = await realpath(target);
+  await outsideRepositories(target, path.dirname(real), real, { run });
+  const key = parseKey(target, await readFile(target, 'utf8'));
+  return {
+    file: target,
+    address: key.address,
+    sign: key.sign,
+    /** A wire transaction with this key's signature in its own slot, as a wallet's signTransaction gives it back. */
+    async signTransaction(wire) {
+      const t = readTransaction(wire);
+      const slot = t.signers.indexOf(key.address);
+      if (slot < 0) throw new KeyFileError(`This transaction is not one ${key.address} signs.`);
+      const signatures = [...t.signatures];
+      signatures[slot] = key.sign(t.message);
+      return wireTransaction(t.message, signatures);
+    },
+    drop: key.drop,
+  };
+}

package/js/approve/live-check.mjs

@@ -53,8 +53,11 @@ export async function checkLive({ live, m, wallet, chain }) {
         `The file names the project ${made.project}, which is not project number ${m.projectNumber} of its owner ${state.owner}.`,
       );
     if (state.owner !== wallet && state.authority !== wallet)
-      throw new LiveMismatch(
-        `The file names the project ${made.project}, which belongs to the wallet ${state.owner}, not to the connected wallet ${wallet}. Your own project number ${m.projectNumber} is at ${own}.`,
+      throw Object.assign(
+        new LiveMismatch(
+          `The file names the project ${made.project}, which belongs to ${state.owner}, not to ${wallet}, the address signing now. (That address’s own project number ${m.projectNumber} would be at ${own}.)`,
+        ),
+        { notOwner: true },
       );
     if (made.treasury && made.treasury !== state.treasury)
       throw new LiveMismatch(`The file says the treasury is ${made.treasury}; on chain it is ${state.treasury}.`);