@source-repo/rpc-cli 4.6.0 → 5.0.0

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { basename, resolve } from 'node:path';
-import { createDerivedAuthenticator, createHmacSigner, createHmacVerifier, createTokenAuthenticator, firstAuthenticator, mintDerivedCredential, defaultSecureWebPort, defaultSecureWebSocketPort, defaultWebPort, defaultWebSocketPort, namespaceProblems, readableNameFor } from '@source-repo/rpc';
+import { createDerivedAuthenticator, createTokenAuthenticator, firstAuthenticator, defaultSecureWebPort, defaultSecureWebSocketPort, defaultWebPort, defaultWebSocketPort, namespaceProblems, readableNameFor } from '@source-repo/rpc';
 import { extractSchema } from './extract.js';
 import { startConsole } from './console.js';
 import { startBroker } from './broker.js';
@@ -15,6 +15,9 @@ import { startFake } from './fake.js';
 import { replaySession, startRecording } from './record.js';
 import { checkPeer, diffPeers } from './conform.js';
 import { bench, benchArguments } from './bench.js';
+import { loadAuthFile, loadSigningKeys, loadTls, scriptCredentials } from './credentials.js';
+import { grantLines, loadAiGrants } from './grants.js';
+import { defaultTaskFile, startTaskFile, taskFileSkeleton, taskFileSkeletonNotes } from './tasks.js';
 /**
  * msgrpc extract  - read the contract out of TypeScript source and write it to a file
  * msgrpc check    - compare the source against a written contract and report breaking changes
@@ -32,6 +35,8 @@ const usage = `source-rpc <command> [options]          --version prints the CLI
   console   browse a live network in a browser: peers, what they expose, calls and events
   broker    run a WebSocket bus: relays between the peers that connect to it, until Ctrl-C
   node      make this machine scriptable from another one, and nothing else, until Ctrl-C
+  run       start console, node and serve roles together from one JSON task file, until Ctrl-C
+            with no file named it runs ./source-rpc.tasks.json; --init writes one to start from
   mcp       serve the network to an MCP client over stdio: list peers, describe them, call them
             stdio carries the protocol, so it is not for interactive use; --port opens a second
             door over streamable HTTP, so two clients can share one node
@@ -70,6 +75,8 @@ const usage = `source-rpc <command> [options]          --version prints the CLI
 
   peers / describe / call / watch
     --broker <url>              an MQTT network, e.g. mqtt://localhost:1883
+                                SOURCE_RPC_MQTT_USERNAME and SOURCE_RPC_MQTT_PASSWORD are used
+                                as broker credentials when set
     --hub <url>                 a socket.io network, e.g. http://hub:7843
                                 one of --broker and --hub is required; both watches both
     --prefix <topic>            topic namespace, default the transport's own
@@ -86,6 +93,8 @@ const usage = `source-rpc <command> [options]          --version prints the CLI
 
   console
     --broker <url>              an MQTT network, e.g. mqtt://localhost:1883
+                                SOURCE_RPC_MQTT_USERNAME and SOURCE_RPC_MQTT_PASSWORD are used
+                                as broker credentials when set
     --hub <url>                 a socket.io network, e.g. http://hub:7843
                                 one of --broker and --hub is required; both watches both
     --prefix <topic>            topic namespace, default the transport's own
@@ -102,6 +111,8 @@ const usage = `source-rpc <command> [options]          --version prints the CLI
 
   mcp
     --broker <url>              an MQTT network
+                                SOURCE_RPC_MQTT_USERNAME and SOURCE_RPC_MQTT_PASSWORD are used
+                                as broker credentials when set
     --hub <url>                 a socket.io network
                                 one of --broker and --hub is required; both watches both
     --prefix <topic>            topic namespace, default the transport's own
@@ -122,6 +133,7 @@ const usage = `source-rpc <command> [options]          --version prints the CLI
                                 nothing can script it. The peer must authenticate as that name,
                                 so the key it presents reaches it out of band - deliberately not
                                 something this bus can hand over
+    --grants <file>             what an AI principal may do here; see node --grants above
     --port <n>                  serve streamable HTTP here as a second door beside stdio, so a
                                 second client shares this node's scripts, fakes and watches
                                 rather than forking them. No default: absent means stdio only
@@ -162,6 +174,19 @@ const usage = `source-rpc <command> [options]          --version prints the CLI
                                 on a broker, --sign at both ends is what makes the grant work:
                                 without it nothing can prove who a caller is and every call is
                                 refused
+    --grants <file>             what an AI principal may do here, as a grants document. Without one
+                                a badged principal may observe and nothing else, which is the
+                                default everywhere. SIGHUP re-reads it, so a grant can be closed
+                                without stopping the node
+
+  run [<file.json>]             defaults to ./source-rpc.tasks.json, in this directory only
+    shared network settings and console, node or serve tasks; relative paths are resolved from the
+    task file. Each task's credentials are its own: a key file under 'sign', an auth file under
+    'auth', or the same secrets written inline in either. Full format:
+    https://source-repo.github.io/rpc/tools/cli#task-files
+    --init                      write a task file to start from, with three roles and fresh signing
+                                secrets, and refuse to write over one that exists. --broker, --hub
+                                and --scriptable-by fill in what they name
 
   strip <file…>
     --out <dir>                 where each decorator-free twin lands, under the same file name.
@@ -252,30 +277,26 @@ const withHistory = (next, previous) => {
     }
     return next;
 };
+/**
+ * HMAC keys for the console, read from a file rather than a flag: a secret on the command line is
+ * visible to anyone who can run ps.
+ *
+ *   { "name": "console-1", "secret": "…", "peers": { "plantServer": "…" } }
+ *
+ * `peers` is optional. Supplying it makes the console check signatures on what it receives too,
+ * which means an unsigned peer's frames are then dropped.
+ */
 const readSigningKeys = (path, command) => {
-    let keys;
     try {
-        keys = JSON.parse(readFileSync(path, 'utf8'));
+        const signing = loadSigningKeys(path);
+        if (signing.readableByOthers)
+            process.stderr.write(`source-rpc ${command}: ${path} is readable by other users\n`);
+        return signing;
     }
     catch (e) {
-        process.stderr.write(`source-rpc ${command}: cannot read keys from ${path}: ${e.message}\n`);
-        process.exit(1);
-    }
-    if (typeof keys.secret !== 'string' || !keys.secret) {
-        process.stderr.write(`source-rpc ${command}: ${path} has no "secret"\n`);
+        process.stderr.write(`source-rpc ${command}: ${e instanceof Error ? e.message : String(e)}\n`);
         process.exit(1);
     }
-    try {
-        // Worth saying out loud: this file is the console's identity on the network.
-        if (statSync(path).mode & 0o077)
-            process.stderr.write(`source-rpc ${command}: ${path} is readable by other users\n`);
-    }
-    catch {
-        // Not worth failing over if the mode cannot be read.
-    }
-    const sign = createHmacSigner(keys.secret);
-    const verify = keys.peers ? createHmacVerifier((peer) => keys.peers?.[peer]) : undefined;
-    return { keys, sign, verify };
 };
 /**
  * Bearer tokens, read from a file or the environment. Never a flag, for the same reason the signing
@@ -299,37 +320,68 @@ const readSigningKeys = (path, command) => {
  * is now impossible either way. Lifetimes are short and renewal does not exist, so stopping the
  * node means its scripts' credentials expire on their own; immediate revocation is the grants
  * work, not this.
+ *
+ * The minting itself lives in credentials.ts, because `run` mints the same credentials from a task
+ * file and two implementations of a credential are two things to get subtly different.
  */
-const scriptCredentials = (auth, issuer, command) => {
-    if (!auth.derive)
-        return undefined;
-    if (!auth.token && !auth.tokens && !auth.issuers)
-        process.stderr.write(`source-rpc ${command}: 'derive' is set but nothing else in the auth file is - scripts will present credentials to a bus that may not be checking any.\n`);
-    return async (script) => {
-        const name = `${script}@${issuer}`;
-        const issuedAt = Date.now();
-        return {
-            name,
-            token: await mintDerivedCredential({
-                credentialId: `${script}-${issuedAt.toString(36)}`,
-                subject: name,
-                // The provenance the AI boundary reads. A script is a program this node started,
-                // whoever wrote it - the honest claim, and never a claim about what wrote it.
-                roles: ['ai-program'],
-                issuer,
-                generation: 2,
-                issuedAt,
-                expiresAt: issuedAt + SCRIPT_CREDENTIAL_MS
-            }, auth.derive)
-        };
-    };
+const scriptCredentialsFor = (auth, issuer, command) => scriptCredentials(auth, issuer, (message) => process.stderr.write(`source-rpc ${command}: ${message}\n`));
+const readAiGrants = (path, command) => {
+    try {
+        return loadAiGrants(path);
+    }
+    catch (e) {
+        process.stderr.write(`source-rpc ${command}: ${e instanceof Error ? e.message : String(e)}\n`);
+        process.exit(1);
+    }
 };
 /**
- * How long a script's credential lasts. Deliberately short of a working day: a credential that
- * outlives the run it was minted for is the failure this design exists to avoid, and a script that
- * needs longer should be a peer with a credential an operator issued.
+ * Refusals reach the operator; permitted calls do not.
+ *
+ * Both are audit, and both belong in the fleet-side sink rather than here - but of the two, a
+ * refusal is the one somebody is standing at a terminal wondering about, and printing every allowed
+ * call would bury it. The sentence the library supplies is the whole line: it already says which
+ * grant was wanted and why the answer was no.
  */
-const SCRIPT_CREDENTIAL_MS = 4 * 60 * 60 * 1000;
+const aiDecisionReporter = (command) => (record) => {
+    if (!record.allowed)
+        process.stderr.write(`source-rpc ${command}: refused ${record.source} calling ${record.method}: ${record.reason}\n`);
+};
+/**
+ * Re-read the grants document on SIGHUP, so a grant can be closed without restarting the node.
+ *
+ * A signal rather than a file watcher, deliberately. A watcher fires on a half-written file and
+ * has to be taught what an atomic replace looks like on three platforms; a signal is an operator
+ * saying *now*, which is the same instinct as everything else here - a change in what is permitted
+ * is something somebody states rather than something that happens when a file is touched.
+ *
+ * A failed reload keeps the document that was already in force. The alternative - falling back to
+ * no document - reads as "closed, therefore safe" and is in fact the node quietly disagreeing with
+ * the policy its operator believes is loaded.
+ */
+const reloadGrantsOnHangUp = (path, initial, apply, command) => {
+    // Not every platform has SIGHUP, and Windows has none of this. Nothing else is affected.
+    if (process.platform === 'win32')
+        return;
+    let current = initial;
+    process.on('SIGHUP', () => {
+        let next;
+        try {
+            next = loadAiGrants(path);
+        }
+        catch (e) {
+            process.stderr.write(`source-rpc ${command}: grants unchanged, ${e instanceof Error ? e.message : String(e)}\n`);
+            return;
+        }
+        // The revision exists so a rollback is visible. Applied anyway - an operator may be
+        // deliberately reverting - but never silently, since the other cause is a stale file.
+        if (current && next.revision < current.revision)
+            process.stderr.write(`source-rpc ${command}: grants revision went backwards, ${current.revision} to ${next.revision}\n`);
+        current = next;
+        apply(next);
+        for (const line of grantLines(next))
+            process.stderr.write(`source-rpc ${command}: ${line}\n`);
+    });
+};
 /**
  * Certificate and key for a server this command opens, or undefined for plain HTTP.
  *
@@ -349,10 +401,10 @@ const readTls = (argv, command) => {
         process.exit(1);
     }
     try {
-        return { cert: readFileSync(cert), key: readFileSync(key) };
+        return loadTls(cert, key);
     }
     catch (e) {
-        process.stderr.write(`source-rpc ${command}: cannot read the certificate or key: ${e.message}\n`);
+        process.stderr.write(`source-rpc ${command}: ${e instanceof Error ? e.message : String(e)}\n`);
         process.exit(1);
     }
 };
@@ -383,29 +435,17 @@ const readAuth = (argv, command) => {
             ...(tokens ? { tokens } : {})
         };
     }
-    let auth;
-    try {
-        auth = JSON.parse(readFileSync(path, 'utf8'));
-    }
-    catch (e) {
-        process.stderr.write(`source-rpc ${command}: cannot read tokens from ${path}: ${e.message}\n`);
-        process.exit(1);
-    }
-    if (!auth.token && !auth.tokens) {
-        // An empty file is the failure that looks like success: the command starts, and the bus it
-        // meant to gate is open. Better to refuse than to run unauthenticated on request.
-        process.stderr.write(`source-rpc ${command}: ${path} has neither "token" nor "tokens"\n`);
-        process.exit(1);
-    }
     try {
+        const loaded = loadAuthFile(path);
         // Worth saying out loud: whoever can read this file can be these peers.
-        if (statSync(path).mode & 0o077)
+        if (loaded.readableByOthers)
             process.stderr.write(`source-rpc ${command}: ${path} is readable by other users\n`);
+        return loaded.auth;
     }
-    catch {
-        // Not worth failing over if the mode cannot be read.
+    catch (e) {
+        process.stderr.write(`source-rpc ${command}: ${e instanceof Error ? e.message : String(e)}\n`);
+        process.exit(1);
     }
-    return auth;
 };
 /**
  * The flags every command that joins a network takes, read once.
@@ -915,17 +955,24 @@ const runMcp = async (argv) => {
             process.exit(1);
         }
     }
-    const credentialFor = scriptsDir ? scriptCredentials(readAuth(argv, 'mcp'), network.name, 'mcp') : undefined;
+    const credentialFor = scriptsDir ? scriptCredentialsFor(readAuth(argv, 'mcp'), network.name, 'mcp') : undefined;
+    const grantsPath = argument(argv, '--grants', '');
+    const aiGrants = grantsPath ? readAiGrants(grantsPath, 'mcp') : undefined;
     const running = await startMcp({ ...network, ...(contracts ? { contracts: resolve(contracts) } : {}), ...(argv.includes('--allow-exec') ? { allowExec: true } : {}),
         ...(scriptsDir ? { scripts: resolve(scriptsDir) } : {}),
         ...(credentialFor ? { credentialFor } : {}),
         ...(scriptableBy.length ? { scriptableBy } : {}),
+        ...(aiGrants ? { aiGrants } : {}),
+        onAiDecision: aiDecisionReporter('mcp'),
         ...(doorPort ? { port: doorPort, host: doorHost, ...(doorToken ? { doorToken } : {}) } : {}) }).catch((e) => {
         // The refusal a wide bind without a token earns arrives here, with its sentence intact.
         process.stderr.write(`source-rpc ${e.message}\n`);
         process.exit(1);
     });
     // Nothing is written to stdout here: it carries the protocol. See mcp.ts.
+    if (scriptsDir || aiGrants)
+        for (const line of grantLines(aiGrants))
+            process.stderr.write(`source-rpc mcp: ${line}\n`);
     const stop = () => void running
         .close()
         .then(() => process.exit(0))
@@ -945,8 +992,17 @@ const runNode = async (argv) => {
         process.stderr.write('source-rpc node: needs --scripts <dir> and at least one --scriptable-by <peer>, or it offers nothing to anybody\n');
         process.exit(1);
     }
-    const credentialFor = scriptCredentials(readAuth(argv, 'node'), network.name, 'node');
-    const running = await startNode({ ...network, scripts: resolve(scriptsDir), scriptableBy, ...(credentialFor ? { credentialFor } : {}) }).catch((e) => {
+    const credentialFor = scriptCredentialsFor(readAuth(argv, 'node'), network.name, 'node');
+    const grantsPath = argument(argv, '--grants', '');
+    const aiGrants = grantsPath ? readAiGrants(grantsPath, 'node') : undefined;
+    const running = await startNode({
+        ...network,
+        scripts: resolve(scriptsDir),
+        scriptableBy,
+        ...(credentialFor ? { credentialFor } : {}),
+        ...(aiGrants ? { aiGrants } : {}),
+        onAiDecision: aiDecisionReporter('node')
+    }).catch((e) => {
         process.stderr.write(`source-rpc node: cannot start: ${e.message}\n`);
         process.exit(1);
     });
@@ -963,6 +1019,12 @@ const runNode = async (argv) => {
         // node is unreachable for the thing it exists to do. Said now rather than discovered as a
         // Forbidden on the other machine.
         process.stderr.write('source-rpc node: on a broker without --sign nothing can prove who a caller is, so every scripting call will be refused. Give both ends keys.\n');
+    // Said whether or not a document was given, because closed-by-default means "it is running" and
+    // "it can do something" are separately true, and this node's scripts carry `ai-program`.
+    for (const line of grantLines(aiGrants))
+        process.stderr.write(`source-rpc node: ${line}\n`);
+    if (grantsPath)
+        reloadGrantsOnHangUp(grantsPath, aiGrants, running.setAiGrants, 'node');
     const stop = () => void running
         .close()
         .then(() => process.exit(0))
@@ -1002,6 +1064,79 @@ const runConsole = async (argv) => {
     process.on('SIGINT', stop);
     process.on('SIGTERM', stop);
 };
+const taskStartedLine = (task) => {
+    if (task.type === 'console')
+        return `${task.id}: console ${task.name} on ${task.url}`;
+    if (task.type === 'node')
+        return `${task.id}: node ${task.name}`;
+    return `${task.id}: serve ${task.name} answering ${task.namespaces?.join(', ')}`;
+};
+/**
+ * Writes a task file to start from, and refuses to write over one that is already there.
+ *
+ * Refusing matters more here than it usually does: the file it would replace holds signing secrets,
+ * and overwriting it does not lose a configuration that can be typed again - it loses the identity
+ * every other machine on the network was told to expect, and does it silently.
+ */
+const initTaskFile = (argv, file) => {
+    const skeleton = taskFileSkeleton({
+        ...(argument(argv, '--broker', '') ? { broker: argument(argv, '--broker', '') } : {}),
+        ...(argument(argv, '--hub', '') ? { hub: argument(argv, '--hub', '') } : {}),
+        ...(argument(argv, '--scriptable-by', '') ? { controller: argument(argv, '--scriptable-by', '') } : {})
+    });
+    try {
+        // wx rather than a check and a write: between the two there is a window, and the thing in it
+        // is a key file.
+        writeFileSync(file, `${JSON.stringify(skeleton, undefined, 4)}\n`, { flag: 'wx', mode: 0o600 });
+    }
+    catch (e) {
+        const already = e.code === 'EEXIST';
+        process.stderr.write(`source-rpc run: ${already ? `${file} already exists, and it may hold this host's signing secrets - name a new file or move that one aside` : `cannot write ${file}: ${e.message}`}\n`);
+        process.exit(1);
+    }
+    for (const note of taskFileSkeletonNotes(file, argument(argv, '--scriptable-by', 'controller')))
+        process.stdout.write(`source-rpc run: ${note}\n`);
+};
+const runTasks = async (argv) => {
+    const [, named, ...extra] = positionals(argv);
+    if (extra.length) {
+        process.stderr.write(`source-rpc run: give it one task file, or none to use ./${defaultTaskFile}\n`);
+        process.exit(1);
+    }
+    const file = named ?? defaultTaskFile;
+    if (argv.includes('--init'))
+        return initTaskFile(argv, file);
+    // Checked before startTaskFile so that the answer to "run" with nothing set up is the thing to
+    // do next, rather than an ENOENT for a file the operator never mentioned.
+    if (!named && !existsSync(file)) {
+        process.stderr.write(`source-rpc run: no ${defaultTaskFile} here, and no task file named. Write one with 'source-rpc run --init', or name one.\n`);
+        process.exit(1);
+    }
+    const running = await startTaskFile(file, {
+        started: (task) => process.stdout.write(`source-rpc run: started ${taskStartedLine(task)}\n`),
+        warning: (message) => process.stderr.write(`source-rpc run: ${message}\n`)
+    });
+    process.stdout.write(`source-rpc run: ${running.tasks.length} tasks running from ${running.file}\n`);
+    let stopping = false;
+    const stop = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        void running
+            .close()
+            .then(() => process.exit(0))
+            .catch((e) => {
+            process.stderr.write(`source-rpc run: shutdown failed: ${e instanceof Error ? e.message : String(e)}\n`);
+            process.exit(1);
+        });
+    };
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+    // The same hang-up that re-reads a node's grants, for every node this file started.
+    if (process.platform !== 'win32')
+        process.on('SIGHUP', () => running.reloadGrants());
+    await new Promise(() => { });
+};
 const main = () => {
     // `source-rpc describe plantServer | head -4` closes stdout while there is still output to
     // write, and Node turns that into an unhandled 'error' event: a stack trace where a command
@@ -1033,7 +1168,10 @@ const main = () => {
         process.exit(1);
     };
     if (command === 'strip') {
-        const files = positionals(argv);
+        // Past the command word, as every other verb here does. Without the slice the first file
+        // to be stripped is one called `strip`, which fails as a missing file rather than saying
+        // no file was named - and it means the command has never worked from the command line.
+        const files = positionals(argv).slice(1);
         const out = argument(argv, '--out', '');
         if (!files.length || !out) {
             process.stderr.write('source-rpc strip: give it one or more .ts files and --out <dir>, e.g. strip scripts/hello.ts --out scripts/stripped\n');
@@ -1069,6 +1207,10 @@ const main = () => {
         void runNode(argv).catch(fail);
         return;
     }
+    if (command === 'run') {
+        void runTasks(argv).catch(fail);
+        return;
+    }
     if (command === 'console') {
         void runConsole(argv).catch(fail);
         return;
@@ -1119,6 +1261,12 @@ const main = () => {
     }
     if (command !== 'extract' && command !== 'check') {
         process.stderr.write(usage);
+        // Pointed at rather than started. Typing the bare command is what someone does to see what
+        // this is, and answering that by joining a bus under whatever identities happen to be in
+        // this directory - and opening a console, and possibly making the machine scriptable -
+        // would be a great deal to have happen while reading the help.
+        if (!command && existsSync(defaultTaskFile))
+            process.stderr.write(`\nthere is a ${defaultTaskFile} here: 'source-rpc run' starts it\n`);
         process.exit(command ? 1 : 0);
     }
     const { schema, diagnostics } = extractSchema(project);